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.
dotnet add package UmbHost.GreenStack.Umbraco.ConfigurationIt supports Umbraco 13 (.NET 8) and Umbraco 17 (.NET 10), and NuGet picks the right build for your site.
When it applies
Section titled “When it applies”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.
What it sets up
Section titled “What it sets up”| Setting | What it does |
|---|---|
| Forwarded headers | Trusts 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 endpoint | Adds /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 checks | Turns off the “HTTPS Configuration” and HSTS health checks, which your container can’t pass because HTTPS is handled at the edge |
| HTTPS runtime validator | Removes the check that stops Production mode starting while Global:UseHttps is false (the Umbraco 13 default) |
| Data Protection keys | Stores keys in /app/keys, which every replica shares, so logins survive deploys and work on every replica |
| Single replica | Turns off server-role election when your site runs one replica, unless you’ve set it yourself |
| Umbraco Forms views | Copies Views/Partials/Forms into the published site, so forms don’t render blank |
| Razor files | Publishes the Razor files the back office needs, unless you’ve set it yourself |
Build warning GREENSTACK001 | Warns if your .csproj turns off view precompilation, which makes every page return a 404 in Production mode |
| Startup warnings | Logs 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:
| Setting | What it does |
|---|---|
| SignalR backplane | Uses your site’s database to keep back office connections in sync, so editors don’t see “No connection with that ID” |
| Server role | Makes every replica a back office server. Without this, pages published from some replicas return a 404 after the next deploy |
| Back office caches | Keeps the back office’s caches in step between replicas |
| Upload folder | Stores 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.
Settings
Section titled “Settings”Both are optional. Set them as environment variables on your service in UmbPanel.
| Variable | Default | Meaning |
|---|---|---|
GreenStack__Enabled | On in a container | Force the package on or off |
GreenStack__DataProtectionKeysPath | /app/keys | Where 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.
What you still set up yourself
Section titled “What you still set up yourself”The package covers configuration only. These stay in your project:
- Production mode in every environment, including staging:
Runtime:Mode=Production,ModelsBuilder:ModelsMode=Nothing(notNone) andHosting:Debug=false. - Your
Dockerfile, running as user1000on port8080. - Versioned asset URLs, such as
asp-append-version="true", because Cloudflare caches static files. - Redirects that leave your
umbpanel.ioaddress alone, because the preview URL uses it. - Your healthcheck path in UmbPanel. Set it to
/healthonce the package is deployed. See How do I add a health check endpoint to my GreenStack site?. App_Pluginsextensions, 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.
Already configured your site by hand?
Section titled “Already configured your site by hand?”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.