How to - Docker
Introduction
Global DCC runs in Docker containers. When starting to work with Global DCC and Docker you should have Docker Desktop installed. This requires a license since we use it commercially. Create an IT ticket to get such a license (Armand says IT was quick and gave him no trouble when he did that). Docker Desktop is necessary for a lot of the stuff we do with Docker, so make sure it is running when you work with Docker (you do not need the window open, it can be running in the background).
When building Docker images it is also important to be online, as much of what it does requires internet access, e.g. fetching images and restoring NuGet packages during the build. Building an image can take a long time, but Docker does its best to cache images and containers so rebuilding is faster.
Before writing code in Global DCC it is a good idea to get familiar with Docker. To do so you can go through this Docker tutorial and this Docker compose tutorial and read the section Docker section in the technology overview.
Beware that Docker can run both Windows and Linux containers but not at the same time (at least Docker Desktop cannot). A lot of documentation/tutorials, including the just mentioned Docker compose tutorial, use Linux, but DCC needs to run in Windows and so Global DCC uses Windows containers. Be aware of the no matching manifest error. In general you get the impression that Docker supports Windows, but really wish it did not.
Docker terminology
Not all docker terminology is intuitive. Here are some explanations of some of it:
| Docker phrase | Meaning |
|---|---|
| Container | A process running on its own virtual machine. Also sometimes used for that virtual machine. |
| Docker Compose | Tool for running multiple containers. |
| docker-compose | File for telling VS how to run a docker-compose.yml file (and possibly docker-compose.override.yml). |
| docker-compose.yml | Config file for docker compose. It tells compose how to start a combination of containers. |
| Image | The data needed for starting a virtual machine (e.g. the files for that VM). |
| Dockerfile | File telling Docker how to build a container. Dockerfile is the name of such a file (no extension). |
| Mount a volume | Add the volume to a container. |
| Volume | A folder that exists both on the machine and in the container. Actually it is a way of mapping a folder in a container to a folder on the host machine, there is also another called "bind mount". |
How to build Docker
Before you can build you need to set the "FEED_ACCESSTOKEN" environment variable. See Getting started.
Using Docker Compose
You can build GlobalDcc.Api.Server, GlobalDcc.Backend.Server, and GlobalDcc.RoadNetManager and then run them, by using Docker Compose. In Visual Studio open the dev folder, and right click the docker-compose project. To build choose "Build", to debug choose "Set as Startup Project" and then press F5.
Building individual images
You can build the /src/api/GlobalDcc.Api.Server/Dockerfile,
/src/backend/GlobalDcc.Backend.Server/Dockerfile, and
/src/roadnet-manager/GlobalDcc.RoadNetManager/Dockerfile in Visual Studio via
right-click -> 'Build Docker Image'.
The first Docker build can take quite some time - have patience. It pulls large windows images, restores all nuget packages and builds the apps. Subsequent builds are usually faster.
Some tips if the build fails
- Try to be connected to AMCS VPN
- Use docker command argument '--network "Default Switch"'
Building via VS uses the msbuild properties for containers from the corresponding app's .csproj file. When building images outside of VS (for example using docker cli), make sure to pass the corresponding arguments to the docker build command.
Troubleshooting
I get an error "no matching manifest for [...] in the manifest list entries" when building Docker.
This is usually caused by trying to run a Windows container whiler Docker Desktop is set up for Linux containers or vice versa.
Try switching container type: In the right side of the Windows taskbar click the
^ symbol (the one that say "Show hidden icons" when hovering over it). Right
click the Docker Desktop icon and choose "Switch to [...] containers...". Try
building again.
My docker build fails with a non descriptive error.
It might help to run the last build container to inspect what files it contains or to run the failing step in the container. If the build output says something like:
---> cd4821852060
Step XX/YY : [Some Docker step]
...
...
... error [Some error message you do not understand]
It might be a good idea to run the container that did the above step XX. To do
this copy the hash listed just before the build step. i.e. cd4821852060. Then
in a PowerShell prompt execute the following command:
docker run -it cd4821852060
This will start the container in interactive mode, and you can inspect what is
in the container or run commands in it from the same PowerShell prompt. To exit
the container again type exit.
I want to get rid of some images/containers, but I don't know if it will break something.
Delete them. They can (almost) always be rebuild or refetched.
I want to attach Visual Studios debugger to a running container.
There is a description of how to do that here.