Running Umbraco in Containers – Share Your Experience

[nikolajlauridsen]

Are you running Umbraco in production using Docker, Kubernetes, or something similar? We'd love to hear how it's working for you! 🤩

• What challenges have you run into? 🤔
• Any workarounds, tweaks, or hoops you've had to jump through? 🛠️
• Any common pitfalls we and others should watch out for? 👀

We’re looking to improve how Umbraco runs in containerized environments, and your input can help shape future updates. If you have a Dockerfile or setup you’d be open to sharing, that would be super helpful too! 😄

Your feedback will help shape how we support containerized deployments in the future. Let’s discuss! 💭

[jrunestone]

Hi!

We're running a load balanced site in Azure with Docker containers via GitHub actions deployments. Our stage and feature environments are also running the same dockerfile. We're also using the same(ish) dockerfile to develop locally with docker-compose. We can simulate the load balanced environment locally quite easily that way.

Overall it's working great. It's quite easy to adopt an Umbraco site to run in a container, even an existing one. I'd say the most work lies in creating/maintaining the deployment flow and the hardest challenges lies in debugging container errors once deployed to the platform. But neither of those things are specific to Umbraco.

Challenges (most of them in development actually):

• Both: Need to pass along license files into the container (umbraco forms for example)
• Dev: Need to map out local volumes properly so as not to run into some issues (in docker-compose)
• Dev: dotnet watch is making the Umbraco models builder trigger a rebuild before the models are rebuilt (added to no watch) - might not be specific to container (don't watch those files)

Production Dockerfile: https://gist.github.com/jrunestone/ab845ec50d3a8636c6bf44355b6cc8fc
Development Dockerfile: https://gist.github.com/jrunestone/713b921d1da31ead4a7e65445efc14c9
Development docker-compose.yml: https://gist.github.com/jrunestone/9c71cb4254e5ba28ed155f89fe117870

[bielu]

@jrunestone i recommend switching to alpine image as default .net image is based on debian with quite a lot vulnerabilities which are not gonna be resolved.

[jrunestone]

Thanks for the tip

[nul800sebastiaan]

Calling @mjpraxis and @CarlSargunar for their container feedback!

[bielu]

I did Umbraco with docker in both Azure and GCP, and my biggest challanges are still 3 things (based on v13):

• Examine and Nucache(I think the nucache bit is redudant because of v15, but yeah didnt test and check what files), which basically force either to map container path for them to keep them persistent or accept really slow cold boots
• Umbraco storying licences through files not db, so we need either include licenses in repository and deploy inside of docker image or map them through docker volumes
• Umbraco logger requirying logs being stored in file, in a lot cases it causes Azure to restart app and move it arround because of size of files. I would love it to be able to store logs anywhere but files system.

The other bits which i usually do is disabling the keep alive job from umbraco, as it just make things harder as you need allow outgoing traffic to app and if you loadbalance with waf it doesnt make sense to do that from app and is better to use healtchecks to keep it alive instead.

[jrunestone]

I have lots of feedback on the Azure hosting and not just container specific if that's of any interest ;)

[mjpraxis]

@nikolajlauridsen we are running several v15 Backoffice instances i Kubernetes(K8S).
I think it was pretty easy to setup and it runs with no errors.

There was some fine-tuning in the beginning making sure that the setting was correct:

The public URL to the Backoffice

• Umbraco__CMS__WebRouting__UmbracoApplicationUrl
• Umbraco__CMS__Security__BackOfficeHost

Making sure that the setting UseHttps in K8S is false, since the internal traffic is HTTP.
This choice do make the Umbraco Health check making warning especially if you also set the Umbraco__CMS__Runtime__Mode to Production. There is a hack that you can remove the UseHttpsValidator in the UmbracoBuilder at startup.

As we are only using the Backoffice, we had to make sure that K8S only had 0 (zero) or 1 pod running.
We are stille adjusting some K8S settings to make it more smooth for the users, when a pod is spinning up.
And we try to monitoring the cpu/ram usage. So we can set the right values for the container app.

[remyili89]

So, as someone who runs the k8s infra and other related cloud resources for our Umbraco team i can remark the following things:

• Passing secrets that Umbraco needs on env level is easily done and tested using ESO (External Secrets Operator), using the same keyvault set Umbraco uses to fetch the rest of the secrets;
• Using the dotnet image to build Umbraco on, it is important to set boundaries on resource usage. Dotnet can go a little bit wild on memory sometimes (cache?)
• Readiness and Liveness probes sometimes take a bit longer and need tweaking, depending on backend.
• I am not an Umbraco/Dotnet developer but i feel like passing a configMap with all the umbraco parameters in there, and read it from there, would be a lot easier and more controlling than passing env vars.

Ill edit this if more things come to mind.

[mjpraxis]

Regarding the configuration/appsettings for dotnet app.
There are several ways of feeding the settings to the app besides appsettings files and environment variables.

I remembered that I once saw a pretty good In-Depth video from .NET conf back in 2023.
Maybe you could get inspired of that: https://www.youtube.com/watch?v=aOXaBZFB0-0

In our solution we get for example the DB connectionstring by environment variabel. Before the UmbracoBuilder is build, we make some changes to it (just something we have to :-) )

[CarlSargunar]

My experience with containers is mostly through Github actions and Azure Container apps, but for my contribs:

• Local developnent is different for everyone, but I find a mix of working with .NET Aspire (as it's SUPER quick to get up and running from cloning a repo) and containers helps - but the same can be achieved with Docker Compose, and it depends on your setup.
• Env variables are used everywhere to configure each container (there are other options, but this worked for me)
• Use OpenTelemetry or the Serilog Application Insights sink to centralize logging is a must - OTel might be overkill, since the serilog app insights sink is enough most of the time, but you don't want to have to go digging for logs
• Licenses - not had to worry about these, but I experimented a while back with storing license in a volume which can then be accessed by any of the containers which needed them

[yannickjemmely]

Hi @nikolajlauridsen ,

We're running multiple websites (low, medium and big size) on our own k8s infrastructure since Umbraco 9. We are currently using the dotnet sdk and runtime official dotnet images. All our sites were recently migrated to Umbraco 13.

Here are key features of our environment:

• Website are deployed through a custom helm chart updated by Gitlab pipeline
• Secret are stored as k8s secrets and injected into the pods regarding the standard Helm mechanism
• A volume is used to store media and logs
• Website are deployed on three environments (development, integration and production) across multiple clusters
• Models generation is always disabled on production environment
• We're able to pull database from production locally to work on "real" data if necessary
• New document types are created in production and then database is pulled locally to generate the model. Finally we push them back in production in the next release
• We use single pod strategy because our CSI driver does not support volume access by multiple pods yet
• Website access is managed by a k8s nginx controller
• Dockerfile is quiet simple and close to the one generated by Visual Studio
• We defined memory and cpu limits and requests for each websites to keep control of resources usages
• Backend authentication is managed through Azure
• We develop and maintain our own nugget package which are stored in a private registry on Gitlab
• Logs are kept as json file but also redirected in console to be able to work with them with Kibana
• We use "User secrets" to deal with secrets locally

Our infrastructure is not perfect yet but allows each developer to work and deploy changes on environments using the Gitlab pipeline. The git flow and project structure is standardized for all website.

I'll be happy to give more information if needed

[nul800sebastiaan]

Just adding a link to this older setup from @liamlaverty (maybe he has new insights since then) https://24days.in/umbraco-cms/2023/automatons/umbraco-docker/

Also some great insights from Scott Hanselman on how to optimize your .NET build to be as tiny as possible (basically treeshaking) and keeping the docker images tiny as well: https://www.youtube.com/watch?v=KqhhaMgbGhU