feat: add full Zonemaster stack with Docker and Spanish UI
- Clone all 5 Zonemaster component repos (LDNS, Engine, CLI, Backend, GUI) - Dockerfile.backend: 8-stage multi-stage build LDNS→Engine→CLI→Backend - Dockerfile.gui: Astro static build served via nginx - docker-compose.yml: backend (internal) + frontend (port 5353) - nginx.conf: root redirects to /es/, /api/ proxied to backend - zonemaster-gui/config.ts: defaultLanguage set to 'es' (Spanish) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,364 @@
|
||||
Release Process - Create Docker Image
|
||||
=====================================
|
||||
|
||||
## Table of contents
|
||||
|
||||
* [1. Overview](#1-overview)
|
||||
* [2. Prerequisite](#2-prerequisite)
|
||||
* [3. Create Docker images](#3-create-docker-images)
|
||||
* [4. Upload images to Docker Hub](#4-upload-images-to-docker-hub)
|
||||
* [5. Image sanity checks][sanity checks]
|
||||
* [6. Handy Docker commands][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]"):
|
||||
```sh
|
||||
[ "$(docker ps -a -q)" != '' ] && docker rm -f $(docker ps -a -q)
|
||||
```
|
||||
```sh
|
||||
[ "$(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:
|
||||
|
||||
```json
|
||||
{
|
||||
"ipv6": true,
|
||||
"fixed-cidr-v6": "2001:db8:1::/64"
|
||||
}
|
||||
```
|
||||
|
||||
Restart the docker daemon:
|
||||
```sh
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
## 3. Create Docker images
|
||||
|
||||
### Clone the repositories
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
(cd zonemaster-ldns; git submodule deinit -f ldns; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(cd zonemaster-engine; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(cd zonemaster-cli; git clean -dfx; git reset --hard; perl Makefile.PL)
|
||||
```
|
||||
```sh
|
||||
(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.
|
||||
```sh
|
||||
make -C zonemaster-ldns all dist docker-build
|
||||
```
|
||||
```sh
|
||||
make -C zonemaster-engine all dist docker-build
|
||||
```
|
||||
```sh
|
||||
make -C zonemaster-cli all dist docker-build
|
||||
```
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
make -C zonemaster-cli docker-tag-version
|
||||
```
|
||||
|
||||
* Add tag "latest":
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
docker images
|
||||
```
|
||||
|
||||
|
||||
### Tag the Zonemaster-Backend image
|
||||
|
||||
For the Zonemaster-Backend image, add a version tag and a tag "latest".
|
||||
|
||||
* Add version tag:
|
||||
```sh
|
||||
make -C zonemaster-backend docker-tag-version
|
||||
```
|
||||
|
||||
* Add tag "latest":
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
docker login
|
||||
```
|
||||
|
||||
The same image is pushed twice with different tags. Verify in the listing
|
||||
above that they have the same ID.
|
||||
|
||||
* Push latest.
|
||||
```sh
|
||||
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.
|
||||
```sh
|
||||
docker push zonemaster/cli:v0.0.0
|
||||
docker push zonemaster/backend:v0.0.0
|
||||
```
|
||||
|
||||
## 5. Image sanity checks
|
||||
|
||||
Zonemaster-LDNS:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/ldns:local perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("9.9.9.9")->query("zonemaster.net")->string'
|
||||
```
|
||||
|
||||
Zonemaster-Engine:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/engine:local perl -MZonemaster::Engine -E 'say join "\n", Zonemaster::Engine->test_module("BASIC", "zonemaster.net")'
|
||||
```
|
||||
|
||||
Zonemaster-CLI:
|
||||
|
||||
```sh
|
||||
docker run --rm zonemaster/cli:local zonemaster.net
|
||||
```
|
||||
|
||||
Zonemaster-Backend:
|
||||
|
||||
Start the backend in the background:
|
||||
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
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:
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
docker ps -a
|
||||
```
|
||||
|
||||
List all images
|
||||
```sh
|
||||
docker images
|
||||
```
|
||||
|
||||
Remove container identified as "ID"
|
||||
```sh
|
||||
docker rm ID
|
||||
```
|
||||
|
||||
Remove image identified as "ID"
|
||||
```sh
|
||||
docker rmi ID
|
||||
```
|
||||
|
||||
Remove all containers
|
||||
```sh
|
||||
docker rm -f $(docker ps -a -q)
|
||||
```
|
||||
|
||||
Remove all images
|
||||
```sh
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
Save an image to a tar file
|
||||
```sh
|
||||
docker save -o docker-zonemaster-cli.tar zonemaster/engine
|
||||
```
|
||||
|
||||
Load an image from a tar file
|
||||
```sh
|
||||
docker load -i docker-zonemaster-cli.tar
|
||||
```
|
||||
|
||||
|
||||
[Ubuntu Build Environment]: ../distrib-testing/Ubuntu-build-environment.md
|
||||
[Sanity checks]: #5-image-sanity-checks
|
||||
[Handy Docker commands]: #6-handy-docker-commands
|
||||
Reference in New Issue
Block a user