Skip to content

What does the UmbHost GreenStack NuGet package do?

UmbHost.GreenStack.Umbraco.Configuration configures an Umbraco site to run correctly on GreenStack. Install it and redeploy. There’s nothing to add to Program.cs.

Terminal window
dotnet add package UmbHost.GreenStack.Umbraco.Configuration

It supports Umbraco 13 (.NET 8) and Umbraco 17 (.NET 10), and NuGet picks the right build for your site.

The package switches itself on inside a container and stays off when you run the site from your IDE, so your local setup is unchanged. To force it on or off, set GreenStack__Enabled to true or false.

SettingWhat it does
Forwarded headersTrusts the X-Forwarded-For and X-Forwarded-Proto headers, so Umbraco sees HTTPS and the visitor’s real IP. HTTPS ends at the Cloudflare edge, not in your container
Health endpointAdds /health (version 1.2.0 or later) using ASP.NET Core’s built-in health checks, for GreenStack’s health probes. You then set it as your healthcheck path in UmbPanel
HTTPS health checksTurns off the “HTTPS Configuration” and HSTS health checks, which your container can’t pass because HTTPS is handled at the edge
HTTPS runtime validatorRemoves the check that stops Production mode starting while Global:UseHttps is false (the Umbraco 13 default)
Data Protection keysStores keys in /app/keys, which every replica shares, so logins survive deploys and work on every replica
Single replicaTurns off server-role election when your site runs one replica, unless you’ve set it yourself
Umbraco Forms viewsCopies Views/Partials/Forms into the published site, so forms don’t render blank
Razor filesPublishes the Razor files the back office needs, unless you’ve set it yourself
Build warning GREENSTACK001Warns if your .csproj turns off view precompilation, which makes every page return a 404 in Production mode
Startup warningsLogs a warning if the site isn’t in Production mode, if your appsettings sets something GreenStack provides (like the connection string), or if a load-balanced replica is set up wrongly

Load balancing (Umbraco 17, 2 or more replicas)

Section titled “Load balancing (Umbraco 17, 2 or more replicas)”

When your site runs 2 or more replicas, the package also sets up everything the Umbraco 17 back office needs to be load balanced:

SettingWhat it does
SignalR backplaneUses your site’s database to keep back office connections in sync, so editors don’t see “No connection with that ID”
Server roleMakes every replica a back office server. Without this, pages published from some replicas return a 404 after the next deploy
Back office cachesKeeps the back office’s caches in step between replicas
Upload folderStores back office uploads on storage every replica shares, unless you’ve set Hosting:TemporaryFileUploadLocation yourself

The load balancing settings need version 1.1.0 or later. UmbPanel tells your site how many replicas it runs through the GreenStack__Replicas environment variable, so normally there is nothing to configure. If your site was set up before UmbPanel added that variable, it may be missing, and the package then quietly skips these settings. Check your service’s environment variables in UmbPanel. A normal deploy doesn’t add it. To add it, edit any environment variable on the service, or save its deployment delay or health check settings without changing them. Either restarts your replicas with the variable in place. If that doesn’t add it, open a support ticket and we’ll sort it out.

Your own configuration always wins: anything marked “unless you’ve set it yourself” only fills a gap.

Both are optional. Set them as environment variables on your service in UmbPanel.

VariableDefaultMeaning
GreenStack__EnabledOn in a containerForce the package on or off
GreenStack__DataProtectionKeysPath/app/keysWhere Data Protection keys are stored

If your site deliberately compiles views at runtime outside Production mode, add <GreenStackAllowRuntimeRazorCompilation>true</GreenStackAllowRuntimeRazorCompilation> to your .csproj to silence GREENSTACK001.

The package covers configuration only. These stay in your project:

  • Production mode in every environment, including staging: Runtime:Mode = Production, ModelsBuilder:ModelsMode = Nothing (not None) and Hosting:Debug = false.
  • Your Dockerfile, running as user 1000 on port 8080.
  • Versioned asset URLs, such as asp-append-version="true", because Cloudflare caches static files.
  • Redirects that leave your umbpanel.io address alone, because the preview URL uses it.
  • Your healthcheck path in UmbPanel. Set it to /health once the package is deployed. See How do I add a health check endpoint to my GreenStack site?.
  • App_Plugins extensions, which you still need to publish from your .csproj.

Leave the application URL, back office host, MainDom lock, Examine directory factory, connection string and ASPNETCORE_ENVIRONMENT out of your configuration. GreenStack provides them.

If you followed the getting started guide before this package existed, you can replace those steps with it. Remove your own versions of what the package does first, so the same thing isn’t set up twice:

  • forwarded headers
  • the HTTPS health check settings
  • the HTTPS validator removal
  • the Data Protection composer
  • on Umbraco 17, the SignalR and load balancing composers and TemporaryFileUploadLocation

Removing your own Data Protection composer matters most. If both are left in place, they can disagree about where the keys are stored, and the keys may end up on one replica’s local disk. Logins then stop working when a request reaches another replica, or after a deploy.