mkdir Umbraco9Docker
cd Umbraco9Docker
Run the following command to install the Umbraco 9 templates into the .NET SDK:
dotnet new -i Umbraco.Templates::*
Run this command to create a new Umbraco 9 website:
dotnet new umbracoIf you wanted to, you could build and run this new website directly without using a container using the `dotnet run` command. ## Building a Docker image for your Umbraco 9 site {#building-a-docker-image-for-your-umbraco-9-site} You have to create a Dockerfile to provide instructions to Docker on how to build the container image. Create a file called Dockerfile and paste in the following content:
FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build WORKDIR /src COPY ["Umbraco9Docker.csproj", "./"] RUN dotnet restore "Umbraco9Docker.csproj" COPY . . WORKDIR "/src/." RUN dotnet publish "Umbraco9Docker.csproj" -c Release -o /app/publish FROM mcr.microsoft.com/dotnet/aspnet:5.0 WORKDIR /app EXPOSE 80 ENV ASPNETCORE_URLS=http://+:80 COPY --from=build /app/publish . ENTRYPOINT ["dotnet", "Umbraco9Docker.dll"]This Dockerfile will do the following: - Copy the Umbraco9Docker.csproj to the src folder. - Restore the NuGet packages specified in Umbraco9Docker.csproj. Docker creates a layer after every step in the Dockerfile. By only copying the Umbraco9Docker.csproj file and then doing a restore, these two layers will only need to be recreated if the Umbraco9Docker.csproj changes. This speeds up the Docker build significantly if no change has been made to the Umbraco9Docker.csproj file. - Copy all the source code to the src folder. - Publish the .NET project in release mode and put the output at /app/publish. - Expose port 80 so the port can be mapped on the container host. - Set an environment variable with key 'ASPNETCORE_URLS' and value 'http://+:80'.
dotnet Umbraco9Docker.dll as the entry point. When the image is run, the entry point will be executed inside the container.
Note: You can also expose port 443, but setting up HTTPS in Docker containers is a blog post of its own. Docker containers commonly expose port 80 and a reverse proxy/load balancer will decrypt/encrypt traffic for HTTPS.
Execute the following command to build your container image:docker build -t umbraco9-image:latest .
This will build your container image and tag the image as 'umbraco9-image:latest'.docker run --rm -t -p 80:80 umbraco9-image:latestHere's what the arguments do: - **\--rm**: clean up the container when the container is stopped - **\-t**: Allocate a pseudo-tty. This will color code the output among things. - **\-p**: Maps port 80 on the host to port 80 in the container - **umbraco9-image:latest**: specifies the container image to run If you browse to [http://localhost:80](http://localhost:80), you should see the website running and Umbraco will prompt you to install the CMS. Unfortunately, you also have to specify the connection string in the wizard. When you enter the connection string, it will be persisted in the *appsettings.json* file in the container, but when you destroy and recreate the container, the changes will be gone and you'll have to go through the wizard again. ### Passing the connection string into the Docker container {#passing-the-connection-string-into-the-docker-container} Instead, you should pass in the connection string some other way. ASP.NET Core's configuration system parses command-line arguments out of the box, so you can pass in the Umbraco connection string as an argument. First, store the connection string in a variable by running these commands:
echo -n Enter Umbraco database connection string: read -s umbracoDbDSNThis will prompt you for the connection string and put the entered value into the `umbracoDbDSN` variable. Next, run this updated `docker run` command:
docker run --rm -t -p 80:80 \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"Umbraco will look for a connection string named `umbracoDbDSN` by default.
Browse to http://localhost:80 again. If you haven't installed Umbraco into the database, it'll prompt you for your desired username and password, but not for a connection string.
After installing Umbraco on the database, you will be taken to the Umbraco back-office at http://localhost:80/umbraco.
{
"$schema": "./umbraco/config/appsettings-schema.json",
"Serilog": {
"MinimumLevel": {...},
"WriteTo": [
{
"Name": "Async",
"Args": {
"configure": [
{
"Name": "Console"
}
]
}
}
]
},
"ConnectionStrings": {...},
"Umbraco": {...}
}
Rebuild the container image with the updated source code:
docker build -t umbraco9-image:latest .
Run the new image:
docker run --rm -t -p 80:80 \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"You should now see all the logs from your running container. ### Persisting file system using volumes and mounts {#persisting-file-system-using-volumes-and-mounts} #### Persisting media files {#persisting-media-files} When you upload files to Umbraco, by default, it will store the files somewhere in the wwwroot/media folder. But when a container is destroyed and recreated, the files uploaded to the wwwroot/media folder are lost.
Note: If you are using a different file provider that stores the files outside of the container, this won't be an issue.
You can use Docker volumes to persist these files even when a container is destroyed and recreated. The first way you could achieve this is by creating a named volume like this:docker run --rm -t -p 80:80 \ -v media-volume:/app/wwwroot/media \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"The command will now also create a volume named 'media-volume' for the */app/wwwroot/media* in the container. If you want to see the files inside this volume from the container host, you can use the following command to get the path to the volume on the host:
docker volume inspect media-volume # output: # [ # { # "CreatedAt": "2021-11-23T22:44:48Z", # "Driver": "local", # "Labels": null, # "Mountpoint": "/var/lib/docker/volumes/media-volume/_data", # "Name": "media-volume", # "Options": null, # "Scope": "local" # } # ]The Mountpoint property will hold the path to your volume on your container host. Alternatively, you can use another option to mount a source directory from the host to a destination directory in the container like this:
docker run --rm -t -p 80:80 \ --mount type=bind,source="$(pwd)/wwwroot/media",destination=/app/wwwroot/media \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"This will mount "$(pwd)/wwwroot/media" on the host where $(pwd) will be replaced with the current directory, and this folder will be mounted to the /app/wwwroot/media folder in the container. The advantage of this approach is that the uploaded files will also be part of your source code. If you don't want the uploaded files to be part of the source code, use the previous approach. With both options, the files uploaded to the media folder will be persisted when the container is destroyed and recreated. #### Persisting log files {#persisting-log-files} The default log configuration in Umbraco is to log to the *umbraco/Logs* folder. You should turn off [the default UmbracoFile sink](https://our.umbraco.com/Documentation/Reference/V9-Config/Serilog/) if you have your own logging infrastructure.
docker run --rm -t -p 80:80 \ --mount type=bind,source="$(pwd)/umbraco/Logs",destination=/app/umbraco/Logs \ --mount type=bind,source="$(pwd)/wwwroot/media",destination=/app/wwwroot/media \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"Now you will be able to find the log files both in the container and in the host at *umbraco/Logs*. #### Persisting Views, Scripts, and Styles {#persisting-views-scripts-and-styles} Log and media files aren't the only way Umbraco interacts with the file system. In the Umbraco back-office, you can also create, update, and delete view files, script files, and style files.
Note: For the Umbraco websites I develop, I am the only one messing with the source code and I'll update the models, views, CSS, and JavaScript outside of the Docker container. So I don't really interact with these files from the Umbraco back-office and don't set up persistent volumes for them.
If you do need to support these back-office capabilities, you can add more mounts like this:docker run --rm -t -p 80:80 \ --mount type=bind,source="$(pwd)/umbraco/Logs",destination=/app/umbraco/Logs \ --mount type=bind,source="$(pwd)/wwwroot/media",destination=/app/wwwroot/media \ --mount type=bind,source="$(pwd)/wwwroot/css",destination=/app/wwwroot/css \ --mount type=bind,source="$(pwd)/wwwroot/scripts",destination=/app/wwwroot/scripts \ --mount type=bind,source="$(pwd)/Views",destination=/app/Views \ umbraco9-image:latest ConnectionStrings:umbracoDbDSN="$umbracoDbDSN"#### Persisting Models from ModelBuilder {#persisting-models-from-modelbuilder} By default, Umbraco 9 will store the models generated from Document Types in-memory without storing them into files. But if you set the models mode to `SourceCodeManual` or `SourceCodeAuto`, the model C# files will be created at *umbraco/models*, or whichever directory you configure using the `ModelsDirectory` property. This means you should create another mount just like the others to persist these files.
Warning: When you're running the Docker container locally, using 'bind' mounts, the code will always be in sync, but if you're running the container elsewhere, the code in the container may drift away from your source code. Any changes to the views, CSS, JavaScript, and models should somehow find their way back into your source control system, or remove the capability to edit these source files altogether.
## Next steps {#next-steps} Now that your Umbraco 9 website is running in a Linux Docker container, you can run it wherever Docker containers are supported, which is pretty much everywhere. If you are an Azure cloud user like me, keep an eye out for more tutorials on how to take this container and host it using Azure App Service, Azure Container Instances, or Azure Container Apps.