Running Umbraco in Docker
Last updated
Was this helpful?
Last updated
Was this helpful?
Exactly how you choose to compose your Dockerfile will depend on your project specific needs. This section is not intended as a comprehensive guide, rather as an overview of topics to be aware of when hosting in Docker.
Docker is a platform for developing, shipping, and running applications in containers. Multiple services exist for hosting these containers. For more information, refer to the
By default, files created inside a container are written to an ephemeral, writable container layer. This means that the files don't persist when the container is removed, and it's challenging to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing.
This has implications when running Umbraco in Docker.
For more information, refer to the .
In general, when working with files and Docker you work in a "push" fashion with read-only layers. When you build, you take all your files and "push" them into this read-only layer.
This means that you should avoid making files on the fly, and instead rely on building your image.
In an Umbraco context, this means you should not create or edit template, script or stylesheet files via the backoffice. These should be deployed as part of your web application and not managed via Umbraco.
Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on creating files on the disk. While this is not a hard requirement, it doesn't provide any value unless you are live editing your site.
Instead, configure models builder to use "source code" mode in development, and "none" in production, as .
Umbraco writes logs to the /umbraco/Logs/
directory. Due to the performance implications of writing to a writable layer,
and the limited size, it is recommended to mount a volume to this directory.
The /umbraco/Data/
directory is used to store temporary files, such as file uploads. Considering the limitations of the writable layer, you should also mount a volume to this directory.
It's recommended to not store media in the writable layer. This is for similar performance reasons as logs, but also for practical hosting reasons. You likely want to persist media files between containers.
Your solution may require some specific files to run, such as license files. You will need to pass these files into the container at build time, or mount them externally.
When running websites in Docker, it's common to do so behind a reverse proxy or load balancer. In these scenarios you will likely handle SSL termination at the reverse proxy. This means that Umbraco will not be aware of the SSL termination, and will complain about not using HTTPS.
Umbraco checks for HTTPS in two locations:
The HstsCheck
health check - This will result in a failed healthcheck.
The UseHttpsValidator
- This will result in a build error, if Production runtime mode is used.
To avoid these checks failing, you can remove them in your project.
The HstsCheck
key is E2048C48-21C5-4BE1-A80B-8062162DF124
so the appsettings will look something like:
The code to remove the validator can look something like:
One solution is to use bind mounts. The ideal setup, though, is to store the media and ImageSharp cache externally. For more information, refer to the .
The health check must be removed via configuration, through the appsettings.json
file, environment variables, or similar. For more information see the .
The UseHttpsValidator
must be removed through code For more information see the .