Getting Started with Umbraco 17 on GreenStack with GitHub
This guide takes you from nothing (or an existing Umbraco 17 project) to a site running on GreenStack, deployed automatically from GitHub every time you push.
If you’d rather not do this yourself, get in touch and we can handle the whole setup for you.
The steps at a glance
Section titled “The steps at a glance”- Choose a starting point: a ready-made template or starter kit, or your existing project.
- Configure an existing project: only needed if you didn’t start from a template.
- Add the GitHub Actions workflow and push your code.
- Connect your registry and image in UmbPanel.
- Add the deploy webhook so every push deploys automatically.
- Check your site.
What you’ll need
Section titled “What you’ll need”- A GreenStack hosting service and access to UmbPanel
- A GitHub account and a repository for your site
- The .NET 10 SDK and Git installed locally
- Optional: Docker Desktop, to test your image locally before pushing
How GreenStack runs your site
Section titled “How GreenStack runs your site”GreenStack runs your site as a Docker container on Docker Swarm, behind a Traefik reverse proxy and Cloudflare. HTTPS is handled before traffic reaches your container, which receives plain HTTP on port 8080. This is the setup Umbraco recommends for Docker.
GreenStack configures a lot for you. Don’t set any of these in your own appsettings files or Dockerfile: GreenStack sets them as environment variables, and yours would conflict.
| Setting | What GreenStack does |
|---|---|
ConnectionStrings:umbracoDbDSN | Points at the database provisioned for your service |
ASPNETCORE_ENVIRONMENT | Set per environment, e.g. Production or Staging |
Umbraco:CMS:WebRouting:UmbracoApplicationUrl and Umbraco:CMS:Security:BackOfficeHost | Set to your *.umbpanel.io preview URL |
Umbraco:CMS:Global:MainDomLock | SqlMainDomLock, which is safe across multiple replicas |
Umbraco:CMS:Examine:LuceneDirectoryFactory | TempFileSystemDirectoryFactory, so each replica keeps its own search index |
GreenStack also provides persistent storage for wwwroot/media, umbraco/Logs, umbraco/Data and /app/keys. Everything else in the container comes from your Docker image and is replaced on every deployment.
Step 1: Choose a starting point
Section titled “Step 1: Choose a starting point”Option A: start from a template or starter kit (recommended)
Section titled “Option A: start from a template or starter kit (recommended)”We publish ready-made Umbraco 17 projects with every GreenStack setting from Step 2 already in place, including the Dockerfile and .dockerignore. Pick the one closest to what you’re building:
| Starting point | What you get | GitHub template |
|---|---|---|
| Blank | A clean Umbraco 17 install | GreenStack.Umbraco |
| Clean Starter Kit | A complete blog-style site using the Clean starter kit | GreenStack.Umbraco.CleanStarterKit |
| The Starter Kit | Umbraco’s official The Starter Kit sample site | GreenStack.Umbraco.TheStarterKit |
| UmBootstrap | A Bootstrap-based site using UmBootstrap | GreenStack.Umbraco.UmBootstrap |
There are two ways to use them.
From GitHub: open the template repository, click Use this template → Create a new repository, then clone your new repository.
With dotnet new: install the template and create a project. For example, for the Clean Starter Kit:
dotnet new install UmbHost.GreenStack.Umbraco.CleanStarterKitdotnet new greenstack-umbraco-cleanstarterkit -n MyProjectdotnet new names the project after -n, and the Dockerfile is updated to match. Swap in the package and template name for the starting point you chose:
| Starting point | Package | Template name |
|---|---|---|
| Blank | UmbHost.GreenStack.Umbraco | greenstack-umbraco |
| Clean Starter Kit | UmbHost.GreenStack.Umbraco.CleanStarterKit | greenstack-umbraco-cleanstarterkit |
| The Starter Kit | UmbHost.GreenStack.Umbraco.TheStarterKit | greenstack-umbraco-thestarterkit |
| UmBootstrap | UmbHost.GreenStack.Umbraco.UmBootstrap | greenstack-umbraco-umbootstrap |
Then create an empty repository on GitHub and push the project to it:
cd MyProjectgit init -b maingit add .git commit -m "Initial commit"git remote add origin https://github.com/YOUR_ACCOUNT/YOUR_REPOSITORY.gitgit push -u origin mainYour project is now configured for GreenStack. Skip to Step 3.
Option B: use your existing Umbraco 17 project
Section titled “Option B: use your existing Umbraco 17 project”Work through Step 2 to add the GreenStack configuration. Every snippet below is taken from the blank template, so you can compare against a working project at any time.
Step 2: Configure an existing project
Section titled “Step 2: Configure an existing project”Starting from a template? Skip this step: it’s already done for you.
Shortcut: the UmbHost GreenStack NuGet package does most of this step for you. Install it with
dotnet add package UmbHost.GreenStack.Umbraco.Configurationand you can skip 2.1 to 2.4, the Razor and Umbraco Forms parts of 2.6, and 2.9 (load balancing needs version 1.1.0 or later). You still need 2.5, publishingApp_Pluginsin 2.6, 2.7, 2.8 and 2.10.
2.1 Trust the proxy’s forwarded headers (Program.cs)
Section titled “2.1 Trust the proxy’s forwarded headers (Program.cs)”Your container only ever sees plain HTTP from the proxy. Without this change, Umbraco thinks every request is insecure, which breaks back office login, URL generation and security features.
Update Program.cs to configure and use the forwarded headers middleware. app.UseForwardedHeaders() must come before app.UseUmbraco():
using Microsoft.AspNetCore.HttpOverrides;
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<ForwardedHeadersOptions>(options =>{ options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto; options.KnownIPNetworks.Clear(); options.KnownProxies.Clear();});
builder.CreateUmbracoBuilder() .AddBackOffice() .AddWebsite() .AddComposers() .Build();
WebApplication app = builder.Build();
await app.BootUmbracoAsync();
// Must come before UseUmbraco()app.UseForwardedHeaders();
app.UseUmbraco() .WithMiddleware(u => { u.UseBackOffice(); u.UseWebsite(); }) .WithEndpoints(u => { u.UseBackOfficeEndpoints(); u.UseWebsiteEndpoints(); });
await app.RunAsync();Keep any other .Add...() calls and middleware your project already has. Only the ForwardedHeadersOptions block and app.UseForwardedHeaders() are new.
See How to forward HTTPS headers for more detail.
2.2 Disable the HTTPS health check (appsettings.json)
Section titled “2.2 Disable the HTTPS health check (appsettings.json)”Umbraco’s HTTPS health check fails behind a proxy, which blocks back office access. Disable it by ID inside your existing Umbraco → CMS section, and stop runtime minification from forcing HTTPS:
{ "Umbraco": { "CMS": { "HealthChecks": { "DisabledChecks": [ { "Id": "EB66BB3B-1BCD-4314-9531-9DA2C1D6D9A7" } ] }, "RuntimeMinification": { "UseHttps": false } } }}Note: The check ID is different in each Umbraco version.
EB66BB3B-1BCD-4314-9531-9DA2C1D6D9A7is the ID for Umbraco 17.
See How do I fix the HTTPS health check for GreenStack? for more detail.
2.3 Remove the HTTPS runtime validator
Section titled “2.3 Remove the HTTPS runtime validator”In Production runtime mode, Umbraco refuses to start unless HTTPS is configured in the application. GreenStack handles HTTPS before your container, so remove that validator. Create Composers/DockerChecksRemoverComposer.cs:
using Umbraco.Cms.Core.Composing;using Umbraco.Cms.Core.DependencyInjection;using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators;
namespace MyProject.Composers;
public class DockerChecksRemoverComposer : IComposer{ public void Compose(IUmbracoBuilder builder) { builder.RuntimeModeValidators() .Remove<UseHttpsValidator>(); }}Change the namespace to match your project. Composers run automatically at startup, so nothing else needs registering.
2.4 Persist Data Protection keys
Section titled “2.4 Persist Data Protection keys”.NET uses Data Protection keys to encrypt login cookies and antiforgery tokens. Your container is replaced on every deployment, so the keys must be stored on GreenStack’s persistent /app/keys folder, or every deployment will log everyone out. Create Composers/DataProtectionComposer.cs:
using Microsoft.AspNetCore.DataProtection;using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Hosting;using Umbraco.Cms.Core.Composing;using Umbraco.Cms.Core.DependencyInjection;
namespace MyProject.Composers;
public class DataProtectionComposer : IComposer{ public void Compose(IUmbracoBuilder builder) { var environment = builder.Services.BuildServiceProvider() .GetRequiredService<IHostEnvironment>();
var keysPath = (environment.IsProduction() || environment.IsStaging()) ? "/app/keys" : Path.Combine(environment.ContentRootPath, "DataProtection-Keys");
if (!Directory.Exists(keysPath)) { Directory.CreateDirectory(keysPath); }
builder.Services.AddDataProtection() .PersistKeysToFileSystem(new DirectoryInfo(keysPath)); }}Important: Keep both
IsProduction()andIsStaging(). A staging environment on GreenStack also has the/app/keysfolder, and leaving it out breaks logins there.
See How to persist .NET Data Protection keys for more detail.
2.5 Run in Production mode (appsettings.Production.json)
Section titled “2.5 Run in Production mode (appsettings.Production.json)”GreenStack sets ASPNETCORE_ENVIRONMENT to Production, so appsettings.Production.json is applied on top of appsettings.json. Use it to put Umbraco into Production runtime mode, which is faster and locks down settings that shouldn’t change on a live site:
{ "$schema": "appsettings-schema.json", "Serilog": { "MinimumLevel": { "Default": "Error" } }, "Umbraco": { "CMS": { "Runtime": { "Mode": "Production" }, "Hosting": { "Debug": false }, "ModelsBuilder": { "ModelsMode": "Nothing" } } }}Production runtime mode has some requirements of its own:
- Views must be precompiled. Remove
<RazorCompileOnBuild>false</RazorCompileOnBuild>and<RazorCompileOnPublish>false</RazorCompileOnPublish>from your.csprojif they’re there. Otherwise every page returns 404 Page not found. - Models must be compiled into your project.
"ModelsMode": "Nothing"(notNone) means models aren’t generated on the live site. Make document type changes locally or in a development environment, then rebuild and redeploy.
Note: Don’t add
UmbracoApplicationUrl,MainDomLock, the Examine directory factory, a connection string orUseHttpshere. GreenStack provides the first four, and HTTPS is handled by the proxy.
2.6 Check your .csproj
Section titled “2.6 Check your .csproj”Make sure the Razor files the back office needs are published:
<PropertyGroup> <!-- Razor files are needed for the backoffice to work correctly --> <CopyRazorGenerateFilesToPublishDirectory>true</CopyRazorGenerateFilesToPublishDirectory></PropertyGroup>If you use Umbraco Forms, its theme views aren’t included when views are precompiled, so copy them to the output. If you have App_Plugins extensions (custom dashboards and property editors), make sure they’re published too:
<ItemGroup> <Content Include="Views\Partials\Forms\**\*" CopyToOutputDirectory="PreserveNewest" /> <Content Include="App_Plugins\**\*" CopyToOutputDirectory="PreserveNewest" /></ItemGroup>2.7 Add a Dockerfile and .dockerignore
Section titled “2.7 Add a Dockerfile and .dockerignore”Create a file named Dockerfile (no extension) in the root of your repository:
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS baseWORKDIR /appEXPOSE 8080
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS buildARG BUILD_CONFIGURATION=ReleaseWORKDIR /srcCOPY . ./RUN dotnet restore "MyProject/MyProject.csproj" --locked-modeRUN dotnet build "MyProject/MyProject.csproj" -c $BUILD_CONFIGURATION --no-restore
FROM build AS publishRUN dotnet publish "MyProject/MyProject.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false --no-build
FROM base AS final
WORKDIR /appCOPY --chown=1000:1000 --from=publish /app/publish .
RUN mkdir -p keys umbraco/Logs umbraco/Data wwwroot/media \ && chown -R 1000:1000 keys umbraco wwwroot
USER 1000:1000ENTRYPOINT ["dotnet", "MyProject.dll", "--console-logger-format=json"]Replace the placeholders with your own project’s names:
| Placeholder | Replace with | Example |
|---|---|---|
MyProject/MyProject.csproj (3 places) | The path from the repository root to your web project’s .csproj | src/Acme.Web/Acme.Web.csproj |
MyProject.dll | Your web project’s assembly name, usually the .csproj name | Acme.Web.dll |
Important: Paths are case-sensitive on Linux.
src/acme.web/Acme.Web.csprojwon’t matchsrc/Acme.Web/Acme.Web.csproj.
Keep the 1000:1000 user, port 8080 and the mkdir line: GreenStack relies on them. Don’t add ASPNETCORE_ENVIRONMENT, ASPNETCORE_URLS or connection strings to the Dockerfile.
Next, create .dockerignore in the root of your repository. It keeps build output, local data and secrets out of your image:
# Git.git.gitignore.gitattributes*/.github
# Build outputs**/bin/**/obj/**/out/**/publish/
# Visual Studio / Rider.vs/.vscode/.idea/*.suo*.user*.userosscache*.sln.docstates*.userprefs.idea/
# NuGet*.nupkg*.snupkgpackages/.nuget/
# Test results[Tt]est[Rr]esult*/[Bb]uild[Ll]og.**.trx*.coverage
# Umbraco specific**/App_Data/**/umbraco/Data/**/umbraco/Logs/**/wwwroot/media/umbraco.config
# Node modules (if you have front-end build)**/node_modules/**/npm-debug.log**/yarn-error.log
# OS files.DS_StoreThumbs.db*.swp*.swo*~
# DockerDockerfile.dockerignoredocker-compose*.yml*.md
# CI/CD.github/.gitlab-ci.ymlazure-pipelines.yml
# Logs*.loglogs/
# Environment files.env.env.*!.env.exampleThe latest versions of both files are in our GreenStack CI/CD samples repository. See also GreenStack starter Dockerfile.
2.8 Exclude UmbPanel addresses from www redirects
Section titled “2.8 Exclude UmbPanel addresses from www redirects”Skip this if your site doesn’t redirect between www and non-www.
GreenStack checks your site’s health, and serves its preview, through its *.umbpanel.io address. If a redirect sends those requests to your own domain, the health check fails and your container is taken out of service, so never redirect *.umbpanel.io. Your site runs on Kestrel, not IIS, so there’s no web.config; add the redirect in Program.cs instead, listing only your production domain:
using Microsoft.AspNetCore.Rewrite;
// Redirect www.example.com to example.com. UmbPanel addresses aren't listed,// so the preview URL and health checks keep working.var rewriteOptions = new RewriteOptions() .AddRedirectToNonWwwPermanent("www.example.com");
app.UseRewriter(rewriteOptions);For the opposite direction, use AddRedirectToWwwPermanent("example.com"). To use IIS-style iisrewrite.xml rules instead, see How do I exclude UmbPanel domains from www redirects?.
2.9 Configure load balancing (only for 2 or more replicas)
Section titled “2.9 Configure load balancing (only for 2 or more replicas)”Skip this if your site runs on a single replica, which is the default. Also skip it if you’ve installed version 1.1.0 or later of the UmbHost GreenStack NuGet package, which does all of it for you.
With 2 or more replicas, the back office runs on every replica, so your site needs all three parts of Umbraco’s load balancing the back office guide below.
SignalR backplane
Section titled “SignalR backplane”The Umbraco 17 back office needs a shared SignalR backplane, or editors see “No connection with that ID” errors. Use your existing GreenStack database as the backplane, following Umbraco’s using existing infrastructure approach. Add the IntelliTect.AspNetCore.SignalR.SqlServer NuGet package:
dotnet add package IntelliTect.AspNetCore.SignalR.SqlServerThen create Composers/SignalRComposer.cs:
using Umbraco.Cms.Core.Composing;
namespace MyProject.Composers;
public class SignalRComposer : IComposer{ public void Compose(IUmbracoBuilder builder) { var connectionString = builder.Config.GetUmbracoConnectionString(); if (connectionString is null) { return; }
builder.Services.AddSignalR().AddSqlServer(connectionString); }}It reuses the connection string GreenStack provides, so there’s nothing to add to appsettings. See How do I configure SignalR for multiple GreenStack replicas?.
Make every replica a back office server
Section titled “Make every replica a back office server”By default Umbraco elects one replica to be the “scheduling publisher” and makes the others “subscribers”. A subscriber never saves page URLs to the database, so a page published from its back office works until the next deploy or restart, then returns a 404 until you republish it. Tell Umbraco that every replica is a back office server. Create Composers/LoadBalancedBackOfficeComposer.cs:
using Umbraco.Cms.Core.Composing;using Umbraco.Cms.Core.DependencyInjection;using Umbraco.Cms.Core.Sync;using Umbraco.Cms.Infrastructure.DependencyInjection;
namespace MyProject.Composers;
public class LoadBalancedBackOfficeComposer : IComposer{ public void Compose(IUmbracoBuilder builder) { builder.SetServerRegistrar(new StaticServerAccessor()); builder.LoadBalanceIsolatedCaches(); }}
public class StaticServerAccessor : IServerRoleAccessor{ public ServerRole CurrentServerRole => ServerRole.SchedulingPublisher;}LoadBalanceIsolatedCaches() keeps the back office’s caches in step, so editors on different replicas don’t see each other’s changes late. Scheduled publishing and webhooks still run once, not once per replica.
Store back office uploads on shared storage
Section titled “Store back office uploads on shared storage”Uploads in the back office are kept in a temporary folder until you save. By default that folder is inside umbraco/Data/TEMP, which is separate on each replica. Move it to storage every replica shares by adding this to appsettings.Production.json:
{ "Umbraco": { "CMS": { "Hosting": { "TemporaryFileUploadLocation": "/app/umbraco/Data/TemporaryFileUploads" } } }}If your site already has replicas and some pages 404 after a restart, see Why do new pages 404 after a deploy on a replicated GreenStack site?
2.10 Check that it builds
Section titled “2.10 Check that it builds”Build in Release mode before you push. Production mode precompiles your views, so view errors (a missing model, a bad @inherits, a package that doesn’t support .NET 10) show up here rather than as 404s on your live site:
dotnet build -c ReleaseIf you have Docker installed, build the image too. It’s the same build GreenStack’s workflow will run:
docker build -t my-site .Commit your changes and push them to GitHub.
Step 3: Add the GitHub Actions workflow
Section titled “Step 3: Add the GitHub Actions workflow”The workflow builds your Docker image, pushes it to the GitHub Container Registry (GHCR), then tells GreenStack to deploy it.
Create .github/workflows/main.yml in your repository:
name: Build and Push Docker Image
on: push: branches: [main] workflow_dispatch:
env: REGISTRY: ghcr.io IMAGE_NAME: GITHUB_ACCOUNT_NAME/DOCKER_IMAGE_NAME
jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write
steps: - uses: actions/checkout@v5 with: submodules: 'true'
- name: Log in to GHCR uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }}
- name: Generate timestamp id: timestamp run: echo "tag=$(date +'%H%M%S%d%m%Y')" >> $GITHUB_OUTPUT
- name: Build and push working-directory: ./ run: | docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.timestamp.outputs.tag }} . docker tag ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.timestamp.outputs.tag }} ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.timestamp.outputs.tag }} docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest echo "Published: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.timestamp.outputs.tag }}"
- name: Trigger webhook run: curl -fS -X POST ${{secrets.WEBHOOK_ENDPOINT}}Change these values:
| Value | Replace with | Example |
|---|---|---|
GITHUB_ACCOUNT_NAME/DOCKER_IMAGE_NAME | Your GitHub username or organisation, and a name for your image, all in lowercase | acme-agency/acme-website |
branches: [main] | The branch that should deploy, if it isn’t main | branches: [master] |
You don’t need to create any secrets for GHCR: the workflow uses GitHub’s built-in GITHUB_TOKEN. If you push to a different registry such as Docker Hub or Azure Container Registry, use the matching workflow from our GitHub Actions samples instead. See What Docker registries does GreenStack support?.
Commit the workflow and push it to main. Then open the Actions tab in your repository and watch it run.
The first run will fail at the “Trigger webhook” step. This is expected. The webhook URL doesn’t exist until GreenStack has deployed your site once (Steps 4 and 5). As long as the Build and push step succeeded, your image is in GHCR and you can carry on.
Step 4: Connect your registry and image in UmbPanel
Section titled “Step 4: Connect your registry and image in UmbPanel”4.1 Create a GitHub access token
Section titled “4.1 Create a GitHub access token”GreenStack needs read access to the image in GHCR.
- In GitHub, go to Settings → Developer settings → Personal access tokens → Tokens (classic) and click Generate new token (classic).
- Enter a descriptive Note, for example
GreenStack image pull. - Choose an Expiration date. You’ll need to update the token in UmbPanel when it expires.
- Select only the
read:packagesscope. - Click Generate token and copy it. GitHub only shows the token once.
4.2 Add the registry in UmbPanel
Section titled “4.2 Add the registry in UmbPanel”- Log in to UmbPanel and open your GreenStack service.
- On the Docker Registries card, click Manage Registries, then Add Registry.
- Fill in the form:
| Field | What to enter |
|---|---|
| Registry Provider | GitHub Container Registry |
| Name | A name for this registry, typically your GitHub username in lowercase |
| Username | Your GitHub username, not your email address. It must be the account that created the token. |
| Personal Access Token | The token from Step 4.1 |
| Organisation Name | The GitHub organisation, if the repository belongs to one. Otherwise leave it blank. |
- Click Save Registry.
4.3 Deploy your image for the first time
Section titled “4.3 Deploy your image for the first time”- Go back to your service and, on the Websites card, click Manage Websites.
- Under Select a Registry, choose the registry you just added and click Save.
- In the Deploy GreenStack panel, enter your Image Name. Enter only the image name, in lowercase: not the registry, username or organisation, and no tag.
Full image name in main.yml | Enter as Image Name |
|---|---|
ghcr.io/acme-agency/acme-website:latest | acme-website |
- Click Initialize GreenStack. This takes several minutes while GreenStack pulls your image and deploys it for the first time.
GreenStack always deploys the latest tag, which the workflow pushes on every run.
Step 5: Add the deploy webhook
Section titled “Step 5: Add the deploy webhook”Once that first deployment has completed, Manage Websites shows your service’s webhook URL under Webhook Details. Copy it, then in GitHub:
- Go to your repository’s Settings → Secrets and variables → Actions and click New repository secret.
- Name it
WEBHOOK_ENDPOINTand paste the webhook URL as its value. - Go to the Actions tab, open the failed run and click Re-run all jobs.
This time every step should pass. From now on, every push to your deploy branch builds a new image and deploys it automatically.
Keep the webhook URL private. Anyone who has it can trigger a deployment of your site.
See Is there a webhook to automatically trigger the release? for more about the webhook.
Step 6: Check your site
Section titled “Step 6: Check your site”Open your site’s Preview URL (a *.umbpanel.io address), which is shown on Manage Websites in UmbPanel.
- The first start can take a few minutes while Umbraco sets up the database. See Why does my GreenStack site take a long time to boot?.
- On a brand-new database, Umbraco asks you to create your first back office user.
- If you started from a starter kit, its sample content is installed on first start.
When you’re ready to go live with your own domain, open your service in UmbPanel and click Manage Hostnames to add your domain, or open a support ticket and we’ll help you set it up.
Next steps
Section titled “Next steps”- Add a staging environment. Each environment is its own GreenStack service deploying from its own branch, for example
stagingfor staging andmainfor production. Promote changes with a pull request fromstagingintomain. - Keep document types and settings in source control with uSync, so they deploy with your code. Use uSync.Complete to move content between environments.
- Scale to more replicas for resilience: open a support ticket to ask us to add replicas. With 2 or more replicas, configure load balancing first.
- Use an AI assistant. Our GreenStack skill and UmbPanel MCP server can configure and deploy all of the above for you.
Troubleshooting
Section titled “Troubleshooting”The first workflow run failed at the “Trigger webhook” step
Section titled “The first workflow run failed at the “Trigger webhook” step”This is expected: the webhook only exists after the first deployment. Follow Step 5, then re-run the workflow.
The workflow fails at the “Build and push” step
Section titled “The workflow fails at the “Build and push” step”Open the failed step’s log. The most common causes are:
- Project not found: the
.csprojpath in yourDockerfiledoesn’t match your repository. Paths are case-sensitive. - Locked mode restore failure: if your project commits a
packages.lock.json, it’s out of date. Rundotnet restore --force-evaluatelocally and commit the updated lock file. - Image name errors: the
IMAGE_NAMEinmain.ymlmust be all lowercase.
”HTTPS is required” when opening the back office
Section titled “”HTTPS is required” when opening the back office”One of the HTTPS changes is missing. Check you’ve completed 2.1, 2.2 and 2.3.
”Invalid redirecturi” when logging in to the back office
Section titled “”Invalid redirecturi” when logging in to the back office”GreenStack sets Umbraco__CMS__Security__BackOfficeHost to your preview URL. Remove any BackOfficeHost value from your own appsettings files. If the error appears after you’ve gone live on your own domain, open a support ticket.
Every page returns “Page not found” after deploying
Section titled “Every page returns “Page not found” after deploying”Usually views aren’t precompiled (see 2.5), a view’s file name casing doesn’t match, or your root content node has no hostname. See My site is showing page not found after deployment.
Views, partials or Umbraco Forms are missing
Section titled “Views, partials or Umbraco Forms are missing”Linux is case-sensitive: PartialAsync("MyPartial") won’t find myPartial.cshtml. Match the casing of every view, partial and folder exactly. For Umbraco Forms and App_Plugins, see 2.6.
The site is down or redirects away from its umbpanel.io address
Section titled “The site is down or redirects away from its umbpanel.io address”A www redirect is probably catching *.umbpanel.io, which fails GreenStack’s health check. See 2.8.
Where are my logs?
Section titled “Where are my logs?”See Why can’t I see my GreenStack logs in UmbPanel? and How do I access my GreenStack persisted files?.
Need help?
Section titled “Need help?”- Browse the other GreenStack articles.
- Open a support ticket in UmbPanel.
- Ask questions or report problems with the samples on GitHub.
If you’d rather not do this yourself, get in touch and we can handle the whole setup for you.