From d81117e1aed600b6899e74dcd88e5452281588c0 Mon Sep 17 00:00:00 2001 From: mole Date: Tue, 6 May 2025 11:29:19 +0200 Subject: [PATCH 01/14] Add article --- .../server-setup/running-umbraco-in-docker.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md new file mode 100644 index 00000000000..836ed21accf --- /dev/null +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -0,0 +1,43 @@ +# Running Umbraco in Docker + +Exactly how you chose to compose your Dockerfile depends on your needs, and your project, so this section is not intended as a guide, +but as a general overview of what to be aware of when hosting in Docker. + +## What is Docker + +Docker is a platform for developing, shipping, and running applications in containers. There exist various services for hosting these containers, +for more information, [refer to the official Docker documentation](https://docs.docker.com/) + +## The Docker file system + +By default, all files created inside a container is written to a ephemeral writable container layer. +This means that the files don't persist when the container is removed, and it's difficult to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing. +This has several implications when running Umbraco in Docker. For more information refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/). + +### General file system consideration + +In general, when working with files and Dockcer you work in a "push" fashion with the read-only layers, that is when you build you take all your files and "push" them into the read-only layer. +This means that you should avoid making files on the fly, and instead rely on building your image, this means that you should not create or edit template files on the fly, the same goes for script and style files. + +Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on creating files on the disk, instead you should use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). + + +### Logs + +Umbraco writes logs to the `/umbraco/Logs/` directory, due to the performance implications of writing to a writable layer, +and the limited size of the writable layer, it is recommended to mount a volume to this directory. + +### Media + +Similarly to logs, it's recommended to not store media in the writable layer, both for performance reasons, +but also for practical development reason, you likely want to persist media files between containers. + +One possible solution here is to again use bind mounts, however the ideal solution is store the media and ImageSharp cache externally, +for more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). + + +## HTTPS + +When running in websites in Docker, it's common to use do so behind a reverse proxy, or load balancers. +In these scenarios you're likely to handle SSL termination at the reverse proxy, this means that Umbraco will not be aware of the SSL termination, and will likely complain about not using HTTPS. + From fd3ee7780cc022aac5797991bae72a22012e1238 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Wed, 7 May 2025 11:21:36 +0200 Subject: [PATCH 02/14] Add HTTPS considerations --- .../server-setup/running-umbraco-in-docker.md | 57 ++++++++++++++++++- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 836ed21accf..5eb884084b2 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -1,6 +1,6 @@ # Running Umbraco in Docker -Exactly how you chose to compose your Dockerfile depends on your needs, and your project, so this section is not intended as a guide, +Exactly how you choose to compose your Dockerfile depends on your needs, and your project, so this section is not intended as a guide, but as a general overview of what to be aware of when hosting in Docker. ## What is Docker @@ -12,14 +12,14 @@ for more information, [refer to the official Docker documentation](https://docs. By default, all files created inside a container is written to a ephemeral writable container layer. This means that the files don't persist when the container is removed, and it's difficult to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing. -This has several implications when running Umbraco in Docker. For more information refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/). +This has several implications when running Umbraco in Docker. For more information, refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/). ### General file system consideration In general, when working with files and Dockcer you work in a "push" fashion with the read-only layers, that is when you build you take all your files and "push" them into the read-only layer. This means that you should avoid making files on the fly, and instead rely on building your image, this means that you should not create or edit template files on the fly, the same goes for script and style files. -Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on creating files on the disk, instead you should use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). +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 simply doesn't provide any value if not live editing your site, instead you should use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). ### Logs @@ -27,6 +27,10 @@ Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on c Umbraco writes logs to the `/umbraco/Logs/` directory, due to the performance implications of writing to a writable layer, and the limited size of the writable layer, it is recommended to mount a volume to this directory. +### Data + +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. + ### Media Similarly to logs, it's recommended to not store media in the writable layer, both for performance reasons, @@ -35,9 +39,56 @@ but also for practical development reason, you likely want to persist media file One possible solution here is to again use bind mounts, however the ideal solution is store the media and ImageSharp cache externally, for more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). +### Required files + +If your solution requires some files to run, for instance license files, you need to pass these files into the container at build time, or mount them externally. ## HTTPS When running in websites in Docker, it's common to use do so behind a reverse proxy, or load balancers. In these scenarios you're likely to handle SSL termination at the reverse proxy, this means that Umbraco will not be aware of the SSL termination, and will likely complain about not using HTTPS. +Umbraco checks for HTTPS in two locations: + +1. The `HstsCheck` health check - This will result in a failed healthcheck. +2. 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. + +### Health Check + +The health check must be removed via configuration, either through the `appsettings.json`, environment variables, or similar, for more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). + +The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like: + +```json + "Umbraco": { + "CMS": { + "HealthChecks" : { + "DisabledChecks": [ + { + "Id": "E2048C48-21C5-4BE1-A80B-8062162DF124" + } + ] + }, + {...} +``` +### Runtime mode validator + +The `UseHttpsValidator` must be removed through code, for more information see the [Runtime mode documentation](runtime-modes.md). + +The code to remove the validator can look something like: + +```C# +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators; + +namespace MySite; + +public class DockerChecksRemover : IComposer +{ + public void Compose(IUmbracoBuilder builder) + => builder.RuntimeModeValidators().Remove(); +} + +``` From ebf85f2536157c2f89de3defcc04d9a8996c8e48 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Wed, 7 May 2025 11:23:25 +0200 Subject: [PATCH 03/14] Add to readme --- 15/umbraco-cms/fundamentals/setup/server-setup/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/README.md b/15/umbraco-cms/fundamentals/setup/server-setup/README.md index 3a12b2f5893..beffe7f3f79 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -29,3 +29,7 @@ Best practices for running Umbraco on Azure Web Apps. ## [Runtime modes](runtime-modes.md) The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment. + +## [Running Umbraco in Docker](running-umbraco-in-docker.md) + +Overview of consideration when running Umbraco in Docker. From 0f2aeaf8b6106b095df8a4cd59ccf5d2fdcf6458 Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Wed, 7 May 2025 11:24:35 +0200 Subject: [PATCH 04/14] Add space --- .../fundamentals/setup/server-setup/running-umbraco-in-docker.md | 1 + 1 file changed, 1 insertion(+) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 5eb884084b2..0d900f7add8 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -73,6 +73,7 @@ The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings }, {...} ``` + ### Runtime mode validator The `UseHttpsValidator` must be removed through code, for more information see the [Runtime mode documentation](runtime-modes.md). From a2cf217dad5975a77f5044e5b8c58b5f597a80cb Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Wed, 7 May 2025 11:33:24 +0200 Subject: [PATCH 05/14] =?UTF-8?q?Try=20and=20appease=20the=20dog=20?= =?UTF-8?q?=F0=9F=90=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../server-setup/running-umbraco-in-docker.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 0d900f7add8..b68b7ce103b 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -1,40 +1,40 @@ # Running Umbraco in Docker -Exactly how you choose to compose your Dockerfile depends on your needs, and your project, so this section is not intended as a guide, +Exactly how you choose to compose your Dockerfile depends on your needs, and your project. This section is not intended as a guide, but as a general overview of what to be aware of when hosting in Docker. ## What is Docker -Docker is a platform for developing, shipping, and running applications in containers. There exist various services for hosting these containers, +Docker is a platform for developing, shipping, and running applications in containers. There exist multiple services for hosting these containers, for more information, [refer to the official Docker documentation](https://docs.docker.com/) ## The Docker file system -By default, all files created inside a container is written to a ephemeral writable container layer. -This means that the files don't persist when the container is removed, and it's difficult to get files out of the container. Additionally, this writable layer is not suitable for performance-critical data processing. -This has several implications when running Umbraco in Docker. For more information, refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/). +By default, all 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 [Docker documentation on storage](https://docs.docker.com/engine/storage/). ### General file system consideration -In general, when working with files and Dockcer you work in a "push" fashion with the read-only layers, that is when you build you take all your files and "push" them into the read-only layer. -This means that you should avoid making files on the fly, and instead rely on building your image, this means that you should not create or edit template files on the fly, the same goes for script and style files. +In general, when working with files and Docker you work in a "push" fashion with the read-only layers. WWhen you build, you take all your files and "push" them into the read-only layer. +This means that you should avoid making files on the fly, and instead rely on building your image. You should not create or edit template files on the fly, the same goes for script and style files. -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 simply doesn't provide any value if not live editing your site, instead you should use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). +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 if not live editing your site. Instead, use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). ### Logs -Umbraco writes logs to the `/umbraco/Logs/` directory, due to the performance implications of writing to a writable layer, +Umbraco writes logs to the `/umbraco/Logs/` directory. Due to the performance implications of writing to a writable layer, and the limited size of the writable layer, it is recommended to mount a volume to this directory. ### Data -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. +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. ### Media Similarly to logs, it's recommended to not store media in the writable layer, both for performance reasons, -but also for practical development reason, you likely want to persist media files between containers. +but also for practical development reasons. You likely want to persist media files between containers. One possible solution here is to again use bind mounts, however the ideal solution is store the media and ImageSharp cache externally, for more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). From 512d082224511a4424f71dbf9f6f6eb85146019f Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Wed, 7 May 2025 11:38:22 +0200 Subject: [PATCH 06/14] Sprinkle some more periods --- .../setup/server-setup/running-umbraco-in-docker.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index b68b7ce103b..49941fc0408 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -25,7 +25,7 @@ Similarly, you shouldn't use InMemory modelsbuilder, since that also relies on c ### Logs Umbraco writes logs to the `/umbraco/Logs/` directory. Due to the performance implications of writing to a writable layer, -and the limited size of the writable layer, it is recommended to mount a volume to this directory. +and the limited size, it is recommended to mount a volume to this directory. ### Data @@ -36,17 +36,17 @@ The `/umbraco/Data/` directory is used to store temporary files, such as file up Similarly to logs, it's recommended to not store media in the writable layer, both for performance reasons, but also for practical development reasons. You likely want to persist media files between containers. -One possible solution here is to again use bind mounts, however the ideal solution is store the media and ImageSharp cache externally, +One possible solution here is to again use bind mounts. The ideal solution is store the media and ImageSharp cache externally, for more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). ### Required files -If your solution requires some files to run, for instance license files, you need to pass these files into the container at build time, or mount them externally. +If your solution requires some files to run, for instance license files. You need to pass these files into the container at build time, or mount them externally. ## HTTPS When running in websites in Docker, it's common to use do so behind a reverse proxy, or load balancers. -In these scenarios you're likely to handle SSL termination at the reverse proxy, this means that Umbraco will not be aware of the SSL termination, and will likely complain about not using HTTPS. +In these scenarios you're likely to handle SSL termination at the reverse proxy. This means that Umbraco will not be aware of the SSL termination, and will likely complain about not using HTTPS. Umbraco checks for HTTPS in two locations: From 16a386c102d8db34a3b72f3c0c9fd2f1ed532537 Mon Sep 17 00:00:00 2001 From: Mole Date: Thu, 8 May 2025 08:35:18 +0200 Subject: [PATCH 07/14] Apply suggestions from code review Co-authored-by: Andy Butland --- .../fundamentals/setup/server-setup/README.md | 2 +- .../server-setup/running-umbraco-in-docker.md | 41 +++++++++++-------- 2 files changed, 24 insertions(+), 19 deletions(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/README.md b/15/umbraco-cms/fundamentals/setup/server-setup/README.md index beffe7f3f79..1ac6c8550e6 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -32,4 +32,4 @@ The runtime mode setting optimizes Umbraco for the best development experience o ## [Running Umbraco in Docker](running-umbraco-in-docker.md) -Overview of consideration when running Umbraco in Docker. +Overview of topics to consider when running Umbraco in Docker. diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 49941fc0408..acf512d6306 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -1,25 +1,31 @@ # Running Umbraco in Docker -Exactly how you choose to compose your Dockerfile depends on your needs, and your project. This section is not intended as a guide, -but as a general overview of what to be aware of when hosting in Docker. +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. ## What is Docker -Docker is a platform for developing, shipping, and running applications in containers. There exist multiple services for hosting these containers, -for more information, [refer to the official Docker documentation](https://docs.docker.com/) +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 official Docker documentation](https://docs.docker.com/) ## The Docker file system -By default, all files created inside a container are written to an ephemeral writable container layer. +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 [Docker documentation on storage](https://docs.docker.com/engine/storage/). + +This has implications when running Umbraco in Docker. + +For more information, refer to the [Docker documentation on storage](https://docs.docker.com/engine/storage/). ### General file system consideration -In general, when working with files and Docker you work in a "push" fashion with the read-only layers. WWhen you build, you take all your files and "push" them into the read-only layer. -This means that you should avoid making files on the fly, and instead rely on building your image. You should not create or edit template files on the fly, the same goes for script and style files. +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 if not live editing your site. -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 if not live editing your site. Instead, use source code in development, and none in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). +Instead, configure models builder to use use "source code" mode in development, and "none" in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). ### Logs @@ -33,20 +39,19 @@ The `/umbraco/Data/` directory is used to store temporary files, such as file up ### Media -Similarly to logs, it's recommended to not store media in the writable layer, both for performance reasons, -but also for practical development reasons. You likely want to persist media files between containers. +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. -One possible solution here is to again use bind mounts. The ideal solution is store the media and ImageSharp cache externally, -for more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). +One possible solution here is to again use bind mounts. The ideal setup though is to store the media and ImageSharp cache externally. For more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). ### Required files -If your solution requires some files to run, for instance license files. You need to pass these files into the container at build time, or mount them externally. +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. ## HTTPS -When running in websites in Docker, it's common to use do so behind a reverse proxy, or load balancers. -In these scenarios you're likely to handle SSL termination at the reverse proxy. This means that Umbraco will not be aware of the SSL termination, and will likely complain about not using HTTPS. +When running in websites in Docker, it's common to use 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: @@ -57,7 +62,7 @@ To avoid these checks failing, you can remove them in your project. ### Health Check -The health check must be removed via configuration, either through the `appsettings.json`, environment variables, or similar, for more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). +The health check must be removed via configuration, through the `appsettings.json` file, environment variables, or similar. For more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like: @@ -76,7 +81,7 @@ The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings ### Runtime mode validator -The `UseHttpsValidator` must be removed through code, for more information see the [Runtime mode documentation](runtime-modes.md). +The `UseHttpsValidator` must be removed through code For more information see the [Runtime mode documentation](runtime-modes.md). The code to remove the validator can look something like: From 13600c11c9b518307c60487c6e14ab1697d0ecc2 Mon Sep 17 00:00:00 2001 From: mole Date: Thu, 8 May 2025 10:36:14 +0200 Subject: [PATCH 08/14] add to SUMMARY --- 15/umbraco-cms/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index 318965ef8f4..ff4c56e2919 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -36,6 +36,7 @@ * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md) * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md) * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md) + * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md) * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md) * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md) * [Standalone File System](fundamentals/setup/server-setup/load-balancing/file-system-replication.md) From 38cd9b26d0fb9d306aa231ba1796c60707a64996 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 8 May 2025 13:45:44 +0200 Subject: [PATCH 09/14] Update 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md --- .../setup/server-setup/running-umbraco-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index acf512d6306..2ff36cd6a63 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -4,7 +4,7 @@ Exactly how you choose to compose your Dockerfile will depend on your project sp ## What is 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 official Docker documentation](https://docs.docker.com/) +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 [official Docker Documentation](https://docs.docker.com/) ## The Docker file system From d135aecb618af701c5460d3c6bf9bcaf81562ce7 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 8 May 2025 13:45:52 +0200 Subject: [PATCH 10/14] Update 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md --- .../setup/server-setup/running-umbraco-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 2ff36cd6a63..0bcfd02ea83 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -23,7 +23,7 @@ This means that you should avoid making files on the fly, and instead rely on bu 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 if not live editing your site. +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 use "source code" mode in development, and "none" in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). From 1cafd3b5488d11676cdbb7e743db598d8e79b4a5 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 8 May 2025 13:45:59 +0200 Subject: [PATCH 11/14] Update 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md --- .../setup/server-setup/running-umbraco-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 0bcfd02ea83..8b1889dee3e 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -25,7 +25,7 @@ In an Umbraco context, this means you should not create or edit template, script 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 use "source code" mode in development, and "none" in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). +Instead, configure models builder to use "source code" mode in development, and "none" in production, as [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). ### Logs From b24b66e1b804d2ad9c290bc15f6cbdfd398e8743 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 8 May 2025 13:46:06 +0200 Subject: [PATCH 12/14] Update 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md --- .../setup/server-setup/running-umbraco-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 8b1889dee3e..583275b30f7 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -42,7 +42,7 @@ The `/umbraco/Data/` directory is used to store temporary files, such as file up 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. -One possible solution here is to again use bind mounts. The ideal setup though is to store the media and ImageSharp cache externally. For more information on this, refer to the [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). +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 [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). ### Required files From c0dd52dfdc20b6ac53ab5a3696f7d9518a1cc372 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Thu, 8 May 2025 13:46:13 +0200 Subject: [PATCH 13/14] Update 15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md --- .../setup/server-setup/running-umbraco-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md index 583275b30f7..7fda09e7aa2 100644 --- a/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md +++ b/15/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -50,7 +50,7 @@ Your solution may require some specific files to run, such as license files. You ## HTTPS -When running in websites in Docker, it's common to use do so behind a reverse proxy, or load balancer. +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: From fa8f59046ae978905de47c48a1077a2d4e708efa Mon Sep 17 00:00:00 2001 From: nikolajlauridsen Date: Fri, 9 May 2025 09:54:04 +0200 Subject: [PATCH 14/14] Add across versions --- 10/umbraco-cms/SUMMARY.md | 1 + .../fundamentals/setup/server-setup/README.md | 4 + .../server-setup/running-umbraco-in-docker.md | 100 ++++++++++++++++++ 13/umbraco-cms/SUMMARY.md | 1 + .../fundamentals/setup/server-setup/README.md | 4 + .../server-setup/running-umbraco-in-docker.md | 100 ++++++++++++++++++ 14/umbraco-cms/SUMMARY.md | 1 + .../fundamentals/setup/server-setup/README.md | 4 + .../server-setup/running-umbraco-in-docker.md | 100 ++++++++++++++++++ 9 files changed, 315 insertions(+) create mode 100644 10/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md create mode 100644 13/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md create mode 100644 14/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md diff --git a/10/umbraco-cms/SUMMARY.md b/10/umbraco-cms/SUMMARY.md index ec30acea629..8a50bd2ac84 100644 --- a/10/umbraco-cms/SUMMARY.md +++ b/10/umbraco-cms/SUMMARY.md @@ -34,6 +34,7 @@ * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md) * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md) * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md) + * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md) * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md) * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md) * [Standalone File System](fundamentals/setup/server-setup/load-balancing/file-system-replication.md) diff --git a/10/umbraco-cms/fundamentals/setup/server-setup/README.md b/10/umbraco-cms/fundamentals/setup/server-setup/README.md index 9d7fc147584..0a057a0da5a 100644 --- a/10/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/10/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -30,3 +30,7 @@ Best practices for running Umbraco on Azure Web Apps. ## [Runtime modes](runtime-modes.md) The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment. + +## [Running Umbraco in Docker](running-umbraco-in-docker.md) + +Overview of topics to consider when running Umbraco in Docker. diff --git a/10/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/10/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md new file mode 100644 index 00000000000..7fda09e7aa2 --- /dev/null +++ b/10/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -0,0 +1,100 @@ +# Running Umbraco in Docker + +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. + +## What is 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 [official Docker Documentation](https://docs.docker.com/) + +## The Docker file system + +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 [Docker documentation on storage](https://docs.docker.com/engine/storage/). + +### General file system consideration + +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 [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). + + +### Logs + +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. + +### Data + +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. + +### Media + +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. + +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 [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). + +### Required files + +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. + +## HTTPS + +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: + +1. The `HstsCheck` health check - This will result in a failed healthcheck. +2. 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. + +### Health Check + +The health check must be removed via configuration, through the `appsettings.json` file, environment variables, or similar. For more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). + +The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like: + +```json + "Umbraco": { + "CMS": { + "HealthChecks" : { + "DisabledChecks": [ + { + "Id": "E2048C48-21C5-4BE1-A80B-8062162DF124" + } + ] + }, + {...} +``` + +### Runtime mode validator + +The `UseHttpsValidator` must be removed through code For more information see the [Runtime mode documentation](runtime-modes.md). + +The code to remove the validator can look something like: + +```C# +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators; + +namespace MySite; + +public class DockerChecksRemover : IComposer +{ + public void Compose(IUmbracoBuilder builder) + => builder.RuntimeModeValidators().Remove(); +} + +``` diff --git a/13/umbraco-cms/SUMMARY.md b/13/umbraco-cms/SUMMARY.md index b18a38d75c5..b87aef3d20a 100644 --- a/13/umbraco-cms/SUMMARY.md +++ b/13/umbraco-cms/SUMMARY.md @@ -34,6 +34,7 @@ * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md) * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md) * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md) + * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md) * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md) * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md) * [Standalone File System](fundamentals/setup/server-setup/load-balancing/file-system-replication.md) diff --git a/13/umbraco-cms/fundamentals/setup/server-setup/README.md b/13/umbraco-cms/fundamentals/setup/server-setup/README.md index 66a23967714..5535e85b0c6 100644 --- a/13/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/13/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -29,3 +29,7 @@ Best practices for running Umbraco on Azure Web Apps. ## [Runtime modes](runtime-modes.md) The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment. + +## [Running Umbraco in Docker](running-umbraco-in-docker.md) + +Overview of topics to consider when running Umbraco in Docker. diff --git a/13/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/13/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md new file mode 100644 index 00000000000..7fda09e7aa2 --- /dev/null +++ b/13/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -0,0 +1,100 @@ +# Running Umbraco in Docker + +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. + +## What is 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 [official Docker Documentation](https://docs.docker.com/) + +## The Docker file system + +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 [Docker documentation on storage](https://docs.docker.com/engine/storage/). + +### General file system consideration + +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 [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). + + +### Logs + +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. + +### Data + +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. + +### Media + +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. + +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 [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). + +### Required files + +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. + +## HTTPS + +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: + +1. The `HstsCheck` health check - This will result in a failed healthcheck. +2. 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. + +### Health Check + +The health check must be removed via configuration, through the `appsettings.json` file, environment variables, or similar. For more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). + +The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like: + +```json + "Umbraco": { + "CMS": { + "HealthChecks" : { + "DisabledChecks": [ + { + "Id": "E2048C48-21C5-4BE1-A80B-8062162DF124" + } + ] + }, + {...} +``` + +### Runtime mode validator + +The `UseHttpsValidator` must be removed through code For more information see the [Runtime mode documentation](runtime-modes.md). + +The code to remove the validator can look something like: + +```C# +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators; + +namespace MySite; + +public class DockerChecksRemover : IComposer +{ + public void Compose(IUmbracoBuilder builder) + => builder.RuntimeModeValidators().Remove(); +} + +``` diff --git a/14/umbraco-cms/SUMMARY.md b/14/umbraco-cms/SUMMARY.md index f24abf09447..60d47c88086 100644 --- a/14/umbraco-cms/SUMMARY.md +++ b/14/umbraco-cms/SUMMARY.md @@ -34,6 +34,7 @@ * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md) * [File And Folder Permissions](fundamentals/setup/server-setup/permissions.md) * [Runtime Modes](fundamentals/setup/server-setup/runtime-modes.md) + * [Running Umbraco in Docker](fundamentals/setup/server-setup/running-umbraco-in-docker.md) * [Umbraco in Load Balanced Environments](fundamentals/setup/server-setup/load-balancing/README.md) * [Load Balancing Azure Web Apps](fundamentals/setup/server-setup/load-balancing/azure-web-apps.md) * [Standalone File System](fundamentals/setup/server-setup/load-balancing/file-system-replication.md) diff --git a/14/umbraco-cms/fundamentals/setup/server-setup/README.md b/14/umbraco-cms/fundamentals/setup/server-setup/README.md index 66a23967714..5535e85b0c6 100644 --- a/14/umbraco-cms/fundamentals/setup/server-setup/README.md +++ b/14/umbraco-cms/fundamentals/setup/server-setup/README.md @@ -29,3 +29,7 @@ Best practices for running Umbraco on Azure Web Apps. ## [Runtime modes](runtime-modes.md) The runtime mode setting optimizes Umbraco for the best development experience or optimal production environment. + +## [Running Umbraco in Docker](running-umbraco-in-docker.md) + +Overview of topics to consider when running Umbraco in Docker. diff --git a/14/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md b/14/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md new file mode 100644 index 00000000000..7fda09e7aa2 --- /dev/null +++ b/14/umbraco-cms/fundamentals/setup/server-setup/running-umbraco-in-docker.md @@ -0,0 +1,100 @@ +# Running Umbraco in Docker + +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. + +## What is 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 [official Docker Documentation](https://docs.docker.com/) + +## The Docker file system + +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 [Docker documentation on storage](https://docs.docker.com/engine/storage/). + +### General file system consideration + +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 [described when using runtime modes](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/runtime-modes). + + +### Logs + +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. + +### Data + +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. + +### Media + +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. + +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 [Azure Blob Storage documentation](https://docs.umbraco.com/umbraco-cms/extending/filesystemproviders/azure-blob-storage). + +### Required files + +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. + +## HTTPS + +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: + +1. The `HstsCheck` health check - This will result in a failed healthcheck. +2. 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. + +### Health Check + +The health check must be removed via configuration, through the `appsettings.json` file, environment variables, or similar. For more information see the [Health Check documentation](../../../reference/configuration/healthchecks.md). + +The `HstsCheck` key is `E2048C48-21C5-4BE1-A80B-8062162DF124` so the appsettings will look something like: + +```json + "Umbraco": { + "CMS": { + "HealthChecks" : { + "DisabledChecks": [ + { + "Id": "E2048C48-21C5-4BE1-A80B-8062162DF124" + } + ] + }, + {...} +``` + +### Runtime mode validator + +The `UseHttpsValidator` must be removed through code For more information see the [Runtime mode documentation](runtime-modes.md). + +The code to remove the validator can look something like: + +```C# +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Infrastructure.Runtime.RuntimeModeValidators; + +namespace MySite; + +public class DockerChecksRemover : IComposer +{ + public void Compose(IUmbracoBuilder builder) + => builder.RuntimeModeValidators().Remove(); +} + +```