Running in Docker

How to work with DynamicWeb 10 and Docker.

This guide will describe how to set up a DynamicWeb 10 solution in a Docker container. Docker is an open-source containerization tool that allows users to run different services in sandbox environments.

Prerequisites

To run DynamicWeb in a Docker container, it's required to prepare the host environment.

Install Docker. On a local development machine, the Docker Desktop application should be sufficient.
If the hosting environment is using an orchestration technology like Kubernetes or K3s, different concerns may arise, therefore these technologies are not covered directly by this guide, though information found here can be used to create charts or configs for those environments.

When it comes to a Docker setup, configurations vary quite a bit. There are a couple of decisions about the infrastructure that needs to be made beforehand. To prevent the contents of the Files folder in DynamicWeb to be wiped when a container is updated, it's recommended to mount the Files folder to either a volume in Docker or to a fixed location on the host. Read more about mounting in Docker here as this is beyond the scope of this guide.

It's recommended to give these issues at least some thought before starting with Docker and DynamicWeb.

Is the database part of the deployment or external, and how is it accessed
How are Files handled
Which application package to use, e.g., CMS or Suite
Which application version to use, e.g., a tag like latest or a specific version like 10.0.3

To get started with DynamicWeb 10 and Docker, these steps should be followed.

Install Docker Desktop
Verify Docker is running
Decide how to handle the database

Deployment

In this section, we'll discuss how to deploy a DynamicWeb 10 Docker image with a database server using docker-compose. Using docker-compose allows for the service environment to be defined by configuration rather than manual actions. This facilitates a consistent process when bringing up and taking down a container, and in update scenarios. The configuration is defined in a docker-compose.yml file. Below is an example of a service environment with DynamicWeb 10 and a database engine packaged together where only DynamicWeb is accessible from the outside.

The DynamicWeb container uses a volume to contain the Files archive that the application uses to store templates and configuration, and the SQL Edge container uses a volume to store the database files. This can be changed in the docker-compose.yml so instead of volumes, it uses folders on the host giving the host access to those files as well. A scenario where this can be advantageous is for backup. However, as mentioned in the Prerequisites section, this is not discussed further in this guide.

The stack (docker-compose.yml) contains an instance of DynamicWeb 10 Suite and an instance of Azure SQL Edge as the database server. If the circumstances require, it's also possible to use the Microsoft SQL Server image or en external database server instead by updating or removing that service in the stack definition.

version: "3"

services:

  mssql:
    image: "mcr.microsoft.com/azure-sql-edge:latest"
    hostname: "mssql"
    restart: unless-stopped
    environment:
      - ACCEPT_EULA=Y
      - MSSQL_SA_PASSWORD=Dynamicweb4All!
    volumes:
      - "mssql-data:/var/opt/mssql"
    networks:
      - dynamicweb

  dw-suite:
    image: "dynamicwebsoftware/dynamicweb-suite:latest" 
    hostname: "dw"
    restart: unless-stopped
    ports:
      - "9001:443"
      - "9000:80"
    volumes:
      - "dw-files:/data/Files"
    networks:
      - dynamicweb
    depends_on:
      - mssql

volumes:
  mssql-data:
  dw-files:

networks:
  dynamicweb: 
    name: Dynamicweb
    driver: bridge

Create a local folder on the host to contain configuration files
Create a docker-compose.yml file and copy the configuration above therein
Open a terminal, shell or command prompt and navigate to the folder with the docker-compose.yml file
Run the command docker compose up -d - note the container name of the SQL container e.g. dwx-mssql-1
Open Docker Desktop and verify that all containers in the stack started successfully

The command docker compose up -d will create the container environment by setting up the network, pulling the required images, and mounting the volumes. Specifying the -d flag will run the containers in daemon mode (in the background).

The official DynamicWeb 10 images expose ports 80 and 443, which means that the DynamicWeb application inside the container is listening on ports 80 and 443. The example above maps the ports 9000 and 9001 on the host to those ports in the container. This means that accessing https://localhost:9001/ on the host will now serve the DynamicWeb 10 application running on port 443 in the container.

Environment variables

Many aspects of the running application can be manipulated using environment variables. Changing the logging configuration or the path in the container where the Files archive is mounted are a few examples of what can be changed with environment variables. Read more about environment variables here.

Adding environment variables to the docker-compose.yml configuration is straightforward.

Find the service to change
Add a section under that service called environment:
Add list items for each environment variable to add - DW_FilesPath=/mydata/Files

See the Certificates section for a concrete example.

The Docker documentation has more information about environment variables here.

Certificates

In order to use an SSL certificate with DynamicWeb 10, it must be either mounted into the container or built into the image. The dw-suite image of the docker-compose.yml in the deployment section includes a default built-in certificate. If you want to add your own certificate to the image it's necessary to mount the certificate into the container. The default path to the certificate used by the host is /data/ssl/dw.pfx with the password dw.

This can be changed by adding environment variables to the docker-compose.yml file.

version: "3"

services:
  ...
  dw-suite:
    ...
    environment:
      - ASPNETCORE_Kestrel__Certificates__Default__Password=[NEW PASSWORD]
      - ASPNETCORE_Kestrel__Certificates__Default__Path=[NEW PATH]

It's important that the user in the container (default 999) has permissions to read the certificate.

In this guide, we're using the officially released DynamicWeb Docker images on Docker Hub, but if you want to create your own Docker image, see this guide for more information.

Installer

When you access the solution URL, you will be met with the DynamicWeb 10 Setup Guide which will help you configure your solution and link to/create a Files-folder, a database, and an administrator user.

When you get to the Setup database-step... DockerSQLSetup ...you should do the following: