Getting Started with Umbraco 17 on GreenStack with GitHub

Welcome to GreenStack! This guide will walk you through everything you need to deploy your Umbraco 17 site to our Docker-based hosting platform. Whether you’re migrating an existing site or starting fresh, we’ve made the process as straightforward as possible.

What You’ll Need

Before we begin, make sure you have:

An Umbraco 17 project ready for deployment
A GreenStack hosting account (sign up here)
Access to a GitHub repository
Basic familiarity with your CI/CD on GitHub

If you find this setup overwhelming or too complicated, get in touch with us as we can handle the whole setup process for you!

Understanding GreenStack Architecture

GreenStack uses Docker Swarm to host containers behind a Traefik reverse proxy and Cloudflare Tunnel to serve your Umbraco sites. This means your application runs in an isolated container environment, with SSL termination handled automatically at the proxy level in the way officially supported by Umbraco.

This architecture requires a few small adjustments to your Umbraco project, which we’ll cover in detail below.

Step 1: Configure Your Umbraco Project

GreenStack handles SSL/TLS at the proxy level, which means your container receives traffic over HTTP internally. Umbraco needs to be configured to trust the forwarded headers from the proxy and to work correctly in this environment.

1.1 Update Program.cs

Open your Program.cs file and configure the forwarded headers middleware. This tells ASP.NET Core to trust the X-Forwarded-For and X-Forwarded-Proto headers from Traefik.

Why is this needed? Without this configuration, Umbraco would see all requests as coming from the internal Docker network over HTTP, which could cause issues with URL generation, security features, and accessing the backoffice.

1.2 Disable the HTTPS Health Check

Umbraco includes a health check that verifies HTTPS is configured. Since GreenStack handles SSL at the proxy level, we need to disable this check to ensure access to the Umbraco backoffice works correctly.

Add the following to your appsettings.json (you can find the most up to date files in the GitHub repository here).

1.3 Remove the HTTPS Runtime Validator

When running in Production mode, Umbraco validates that HTTPS is configured at the application level. We need to remove this validator since SSL is handled externally.

Create a new file called DockerChecksRemoverComposer.cs in your project (you can find the most up to date files in the GitHub repository here).

This composer runs automatically when your application starts and removes the HTTPS validator from the runtime checks.

Step 2: Create Your Dockerfile

GreenStack uses Docker to containerise and deploy your application. You’ll need a Dockerfile in the root of your repository.

Create a file named Dockerfile (no extension) (you can find the most up to date files in the GitHub repository here).

Important: Replace WEB_PROJECT_FOLDER/WEB_PROJECT_NAME.csproj with the folder and csproj file name of your Umbraco project. You will also need to replace WEB_PROJECT_NAME.dll with the name of your web project’s DLL (typically this is the same as your web project csproj file).

2.1 Create a .dockerignore File

To speed up builds and reduce image size, create a .dockerignore file in your repository root (you can find the most up to date files in the GitHub repository here).

Step 3: Set Up CI/CD

GreenStack integrates with GitHub Actions to automatically build and deploy your site when you push changes. We provide ready-made templates for GitHub Actions.

GitHub Actions Setup

Create the following directory structure in your repository:

.github/
  workflows/
    deploy.yml

Create .github/workflows/main.yml (you can find the most up to date files in the GitHub repository here).

Important: Replace GITHUB_ACCOUNT_NAME/DOCKER_IMAGE_NAME with the name of your Docker image.

Step 4: Configure Your GreenStack Site

4.1 Log in to UmbPanel

Access your control panel at www.umbpanel.io and navigate to your GreenStack service.

4.2 Configure Docker Registry

In GitHub go to Settings → Developer settings → Personal access tokens → Tokens (classic). On this page click on the Generate new token (classic) button.

Enter a descriptive name in the Note field
Set an expiry date for the token
Select read:packages scope
Click Generate token

Make a note of the generated token as you cannot see it again!

In UmbPanel enter the requested registry details in the form:

Field Name	Description
`Name`	Your registry name, this is typically the username for your account in lowercase
`Username`	Your GitHub username (the one shown on your GitHub profile / used to log in) — not the email address associated with your GitHub account. This must match the user that generated the personal access token.
`Access Token`	The token we previously generated
`Organisation Name`	If the repository is stored in a GitHub Organisation enter the name here

Click Save to continue onto the next step.

4.3 Configure Docker Image

Next you will need to enter the Docker image name (this was entered in the main.yml file earlier). This should be all lowercase and minus any labels.

Important: Enter only the image name itself — do not include the registry host, your GitHub username, or your organisation name. Those have already been captured in the registry step above.

For example, if your full image reference in main.yml is:

ghcr.io/umbhost/my-umbraco-site:latest

then the value you enter here is just:

my-umbraco-site

…not umbhost/my-umbraco-site and not ghcr.io/umbhost/my-umbraco-site.

Important: GreenStack looks to the label called latest automatically.

4.4 Configure GitHub Secrets

In your GitHub repository, go to Settings → Secrets and variables → Actions and add the following secret:

Secret Name	Description
`WEBHOOK_ENDPOINT`	Your deployment webhook URL

You can find the webhook value in the UmbPanel control panel.

Heads up: the webhook URL isn’t generated until after your initial deployment has run, so the first push to main is expected to fail at the trigger step. Once that first build has completed and the image has been pulled by GreenStack, head back to UmbPanel to grab the webhook URL, add it as the WEBHOOK_ENDPOINT secret, and re-run the workflow (or push another commit) — subsequent deployments will then complete end-to-end.

Step 5: Deploy!

Once everything is configured:

Commit and push your changes to the main branch
GitHub Actions will automatically build your Docker image
The image is pushed to your GitHub registry
The webhook will trigger the deployment

You can monitor the deployment progress in both GitHub Actions, and you can see the task status in UmbPanel once deployed.

Troubleshooting

My first GitHub Actions run failed at the webhook step

This is expected. The deployment webhook URL is only generated after your first deployment to GreenStack, so the WEBHOOK_ENDPOINT secret can’t exist on the very first push. The image will still build and push to your registry — only the final trigger step will fail. Once the initial deployment has been completed in UmbPanel, copy the webhook URL from your service, add it as the WEBHOOK_ENDPOINT repository secret, and re-run the workflow. From then on, every push will deploy automatically.

”HTTPS is required” when trying to access the backoffice

Make sure you’ve completed all three configuration steps in Step 1. The health check, runtime validator, and forwarded headers all need to be configured correctly.

”Invalid redirecturi” when trying to access the backoffice

Make sure the environment variable called Umbraco__CMS__Security__BackOfficeHost contains the umbpanel.io preview URL for your instance. After your site has gone live you may need to update this variable to contain your site’s actual URL.

Build Fails with “Project Not Found”

Verify that the project path in your Dockerfile matches your actual project structure. The path is case-sensitive on Linux.

Further Resources

GreenStack CI/CD Samples Repository — Ready-to-use templates and examples
UmbHost Knowledge Base — Detailed documentation and guides
UmbHost Support — Our friendly support team is here to help

Need Help?

If you run into any issues or have questions, we’re here to help! You can:

Open a support ticket through My.UmbHost
Join the discussion on our GitHub repository
Report issues on our GitHub repository

If you find this setup overwhelming or too complicated, get in touch with us as we can handle the whole setup process for you!