zonemaster.es/zonemaster/docs/internal/maintenance/ReleaseProcess-create-docker-image.md

Release Process - Create Docker Image

Table of contents

• 1. Overview
• 2. Prerequisite
• 3. Create Docker images
• 4. Upload images to Docker Hub
• 5. Image sanity checks
• 6. Handy Docker commands

1. Overview

This document covers two stages in the release processes:

1. Creating Docker images for testing.
2. Creating Docker image for publishing on Docker Hub

Presently only Zonemaster-CLI is published, and therefore only Zonemaster-LDNS, Zonemaster-Engine and Zonemaster-CLI are covered here.

2. Prerequisite

Environment

The steps in this documents are assumed to be executed on a computer installed as an Ubuntu Build Environment computer. It could work on another OS as long as the same support is available.

All commands in this instruction are assumed to be executed from the one and the same directory. If you run cd, then you have to run cd back to the start directory.

The Docker environment is assumed to be clean. Consider running the following commands to clean up before proceeding (see section "Handy Docker commands"):

[ "$(docker ps -a -q)" != '' ] && docker rm -f $(docker ps -a -q)

[ "$(docker image ls -q)" != '' ] && docker image prune -a

Enable IPv6 support

Docker has no IPv6 support by default. On Linux it can be enabled. Do that unless already done, or else zonemaster-cli will report errors when trying to access servers on IPv6.

Create or update /etc/docker/daemon.json. This is a minimal file that enables IPv6 support:

{
    "ipv6": true,
    "fixed-cidr-v6": "2001:db8:1::/64"
}

Restart the docker daemon:

sudo systemctl restart docker

3. Create Docker images

Clone the repositories

git clone https://github.com/zonemaster/zonemaster-ldns
git clone https://github.com/zonemaster/zonemaster-engine
git clone https://github.com/zonemaster/zonemaster-cli
git clone https://github.com/zonemaster/zonemaster-backend

Check out right branch depending on the use case

• Check out develop branch when creating an image for release testing:

git -C zonemaster-ldns checkout origin/develop
git -C zonemaster-engine checkout origin/develop
git -C zonemaster-cli checkout origin/develop
git -C zonemaster-backend checkout origin/develop

• Check out master branch when creating an image for Docker Hub at release, or when creating an image based on release version:

git -C zonemaster-ldns checkout origin/master
git -C zonemaster-engine checkout origin/master
git -C zonemaster-cli checkout origin/master
git -C zonemaster-backend checkout origin/master

Make sure repositories are clean and create Makefile in all repositories

(cd zonemaster-ldns; git submodule deinit -f ldns; git clean -dfx; git reset --hard; perl Makefile.PL)

(cd zonemaster-engine; git clean -dfx; git reset --hard; perl Makefile.PL)

(cd zonemaster-cli; git clean -dfx; git reset --hard; perl Makefile.PL)

(cd zonemaster-backend; git clean -dfx; git reset --hard; perl Makefile.PL)

Create images

Create an image for each repository. That image will be tagged "local". The images must be created in order since there is a dependency on the previous image in each step.

make -C zonemaster-ldns all dist docker-build

make -C zonemaster-engine all dist docker-build

make -C zonemaster-cli all dist docker-build

make -C zonemaster-backend all dist docker-build

Determine version of Zonemaster-CLI image

The description in this section must be followed if the image is to be uploaded to Docker Hub below. If not, this section can be skipped, modified or followed depending on needs.

The version of Zonemaster-CLI has the format "v0.0.0" and it is the normal version of the Docker image too. If needed a "dash version" is used on the Docker images, and that has the format "v0.0.0-N" where "v0.0.0" is the same version as Zonemaster-CLI, and "N" is a positive integer starting with "1".

First determine what the version should be. Compare the version of Zonemaster-Cli just built with the highest version of the image uploaded to Docker Hub. There are three valid possibilities:

1. The version on Docker Hub has lower version than the local version. If so set the tags of the image with the simple steps below ignoring "dash versions".

Example: version on Docker Hub is v6.0.0 or v6.0.0-1, local version is v6.0.1, new image will have version v6.0.1.

2. The version on Docker Hub has the same version as the local version. Set the version on the new Docker image to be "v0.0.0-1" where "v0.0.0" is equal to the local version.

Example: version on Docker Hub is v6.0.1, local version is v6.0.1, new image will have version v6.0.1-1.

3. The version on Docker Hub is a "dash version" where the "v0.0.0" part is the same as the local version. Set the version of the new Docker image to be "v0.0.0-N" where "v0.0.0" is equal to the local version and "N" is the integer incremented by 1 compared to the version on Docker Hub.

Example: version on Docker Hub is v6.0.1-1, local version is v6.0.1, new image will have version v6.0.1-2.

Determine version of Zonemaster-Backend image

The version of Zonemaster-Backend follows the same rules as Zonemaster-CLI.

Tag the Zonemaster-CLI image

For the Zonemaster-CLI image, add a version tag and a tag "latest".

• Add version tag:

make -C zonemaster-cli docker-tag-version

• Add tag "latest":

make -C zonemaster-cli docker-tag-latest

• If "dash version" is to be used, set tag with that version and remove tag with plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be the "dash version" determined above:

cd zonemaster-cli
docker tag zonemaster/cli:local zonemaster/cli:v0.0.0-N 
docker rmi zonemaster/cli:v0.0.0

All the created images can now be listed. Also consider doing sanity checks to verify that all images work. Images without tag are temporary images without further use. List images:

docker images

Tag the Zonemaster-Backend image

For the Zonemaster-Backend image, add a version tag and a tag "latest".

• Add version tag:

make -C zonemaster-backend docker-tag-version

• Add tag "latest":

make -C zonemaster-backend docker-tag-latest

• If "dash version" is to be used, set tag with that version and remove tag with plain version where "v0.0.0" should be the local version and "v0.0.0-N" should be the "dash version" determined above:

cd zonemaster-backend
docker tag zonemaster/backend:local zonemaster/backend:v0.0.0-N 
docker rmi zonemaster/backend:v0.0.0

All the created images can now be listed. Also consider doing sanity checks to verify that all images work. Images without tag are temporary images without further use. List images:

docker images

4. Upload images to Docker Hub

To upload an image to the Zonemaster Docker Hub organization you have to have a Docker Hub account and the authorization to upload images.

docker login

The same image is pushed twice with different tags. Verify in the listing above that they have the same ID.

• Push latest.

docker push zonemaster/cli:latest
docker push zonemaster/backend:latest

• Set correct version (see listing above) and push image with version tag. If "dash version" is used, use "v0.0.0-N" set to correct version instead.

docker push zonemaster/cli:v0.0.0
docker push zonemaster/backend:v0.0.0

5. Image sanity checks

Zonemaster-LDNS:

docker run --rm zonemaster/ldns:local perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("9.9.9.9")->query("zonemaster.net")->string'

Zonemaster-Engine:

docker run --rm zonemaster/engine:local perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'

Zonemaster-CLI:

docker run --rm zonemaster/cli:local zonemaster.net

Zonemaster-Backend:

Start the backend in the background:

docker run --rm -p 5000:5000 --name zm -d zonemaster/backend:local full

Run docker ps -a. The container named zm should be running.

Run a test through the backend:

docker run -ti --rm --net host zonemaster/backend:local zmtest zonemaster.net

The output should be a JSON object containing, among other things, a list of message tags in JSON format.

Test the correct operation of the zmb tool by running a test:

docker run -ti --rm --net host zonemaster/backend:local zmb start_domain_test --domain zonemaster.net
docker run -ti --rm --net host zonemaster/backend:local zmb get_test_results --test-id be98f37d3b137ce0 --lang en

The output should be a JSON object, similar to the previous one.

Finally, stop the backend:

docker stop zm

And run docker ps -a to ensure that the backend is no longer running.

6. Handy Docker commands

List all containers, including stopped containers.

docker ps -a

List all images

docker images

Remove container identified as "ID"

docker rm ID

Remove image identified as "ID"

docker rmi ID

Remove all containers

docker rm -f $(docker ps -a -q)

Remove all images

docker image prune -a

Save an image to a tar file

docker save -o docker-zonemaster-cli.tar zonemaster/engine

Load an image from a tar file

docker load -i docker-zonemaster-cli.tar