Getting Started
GreenStack & GitHub

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) with the following content (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 projects 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) with:

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:

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: 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:

You can find the webhook value in the UmbPanel control panel 

Step 5: Deploy!

Once everything is configured:

1. Commit and push your changes to the main branch

2. GitHub Actions will automatically build your Docker image

3. The image is pushed to your GitHub registry

4. 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

"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 sites 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!