Use bundled compose instead of system one to reduce issues with different versions of compose

aequitas · mxsasha · commit 41938eca573d · 2026-02-26T13:09:55.000+01:00
- simplify deployment instructions by removing version pins as those where for Docker versions more than a year old
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -19,11 +19,12 @@ env:
   # should be used to transfer images between jobs. Forked and dependabot builds don't
   # have permission to push to registry.
   use_registry: ${{ ! (github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.head_ref, 'dependabot/'))) }}
+  COMPOSE_VERSION: 2.40.3
 
 jobs:
   # builds all docker images in parallel
   build-docker:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     strategy:
       matrix:
@@ -227,7 +228,7 @@ jobs:
           retention-days: 1
 
   docs:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     needs: [build-docker]
     steps:
       - name: Branch deployment docs
@@ -272,7 +273,7 @@ jobs:
           sudo apt-get update
 
           # upgrade Docker
-          sudo apt install --upgrade docker-ce docker-compose-plugin=2.33.0\*
+          sudo apt install --upgrade docker-ce docker-compose-plugin=$COMPOSE_VERSION\*
 
       - name: Debug info
         run: |
@@ -374,7 +375,7 @@ jobs:
   lintcheck:
     name: lint/check
     needs: [build-docker]
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     env:
       # used in `compose.yaml` files to determine version of images to pull
@@ -452,7 +453,7 @@ jobs:
           sudo apt-get update
 
           # upgrade Docker
-          sudo apt install --upgrade docker-ce docker-compose-plugin=2.33.0\*
+          sudo apt install --upgrade docker-ce docker-compose-plugin=$COMPOSE_VERSION\*
 
       - name: Debug info
         run: |
@@ -539,7 +540,7 @@ jobs:
           sudo apt-get update
 
           # upgrade Docker
-          sudo apt install --upgrade docker-ce docker-compose-plugin=2.33.0\*
+          sudo apt install --upgrade docker-ce docker-compose-plugin=$COMPOSE_VERSION\*
 
       - name: Debug info
         run: |
@@ -657,7 +658,7 @@ jobs:
           sudo apt-get update
 
           # upgrade Docker
-          sudo apt install --upgrade docker-ce docker-compose-plugin=2.33.0\*
+          sudo apt install --upgrade docker-ce docker-compose-plugin=$COMPOSE_VERSION\*
 
       - name: Debug info
         run: |
diff --git a/docker/compose-dist.sh b/docker/compose-dist.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+
+# wrapper to run the right compose command with the right environment variables from the util container
+
+set -e
+
+# determine install base for multi environment deployments (parent of directory containing this file)
+INTERNETNL_INSTALL_BASE=$(dirname "$(dirname "$(readlink -f "$0")")")
+
+exec docker run -ti --rm --pull=never \
+  --volume /var/run/docker.sock:/var/run/docker.sock \
+  --volume "$INTERNETNL_INSTALL_BASE:/opt/Internet.nl" \
+  --workdir /opt/Internet.nl \
+  --network none \
+  "ghcr.io/internetstandards/util:$RELEASE" \
+  docker compose --env-file=docker/defaults.env --env-file=docker/host.env --env-file=docker/local.env "$@"
diff --git a/docker/deploy.sh b/docker/deploy.sh
@@ -8,6 +8,9 @@ echo "Deploying release: $RELEASE"
 
 # copy release specific support files
 cp -v /dist/docker/* docker
+# put $RELEASE into the compose.sh file
+envsubst '$RELEASE' < docker/compose-dist.sh > docker/compose.sh
+chmod a+x docker/compose.sh
 
 # set release version in local.env config
 echo "RELEASE='$RELEASE' # deploy $(date)" >> docker/local.env
diff --git a/docker/util.Dockerfile b/docker/util.Dockerfile
@@ -1,6 +1,6 @@
-FROM alpine:3.20.3
+FROM alpine:3.22
 
-RUN apk add --no-cache curl postgresql15 python3 py3-prometheus-client py3-requests jq docker-cli docker-cli-compose pigz jq
+RUN apk add --no-cache curl postgresql15 python3 py3-prometheus-client py3-requests jq docker-cli docker-cli-compose pigz jq envsubst
 
 # install cron tasks
 COPY docker/cron/periodic /etc/periodic/
@@ -25,6 +25,7 @@ COPY docker/host-dist.env /dist/docker/
 COPY docker/host-multi-dist.env /dist/docker/
 COPY docker/compose.yaml /dist/docker/
 COPY docker/user_manage.sh /dist/docker/
+COPY docker/compose-dist.sh /dist/docker/
 RUN chmod a-w /dist/docker/*
 
 # add release as label for auto_update feature
diff --git a/documentation/Docker-DNS.md b/documentation/Docker-DNS.md
@@ -114,11 +114,11 @@ Letsencrypt account ID and private key are stored in a Docker volume for persist
 
 When deploying a new instance, first complete the full setup. After that perform the following steps to restore the account:
 
-    docker compose --project-name=internetnl-prod stop webserver
+    /opt/Internet.nl/docker/compose.sh stop webserver
     rm -rf /var/lib/docker/volumes/internetnl-prod_certbot-config/_data/*
     cp -r <location of backed up _data directory> /var/lib/docker/volumes/internetnl-prod_certbot-config/_data/
-    docker compose --project-name=internetnl-prod start webserver
+    /opt/Internet.nl/docker/compose.sh start webserver
 
 The certbot instance in the webserver container should start requesting a certificate for the domain after at most 1 minute. You can check the progress using:
 
-    docker compose --project-name=internetnl-prod exec webserver cat /var/log/letsencrypt/letsencrypt.log
+    /opt/Internet.nl/docker/compose.sh exec webserver cat /var/log/letsencrypt/letsencrypt.log
diff --git a/documentation/Docker-deployment-batch.md b/documentation/Docker-deployment-batch.md
@@ -35,29 +35,21 @@ A domain name is recommended to access the server and have Letsencrypt TLS be se
 
 After installation and basic configuration of the OS switch to `root` user.
 
-Run the following command to install required dependencies:
-
-    apt update
-    apt install -yqq ca-certificates curl gnupg
-
-Setup Docker Apt repository:
-
-    install -m 0755 -d /etc/apt/keyrings
-    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-    chmod a+r /etc/apt/keyrings/docker.gpg
-    echo "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
-      "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" > /etc/apt/sources.list.d/docker.list
-    apt update
-
-Install Docker:
-
-    apt install -yqq docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-
-Configure Docker for IPv6 and Live restore:
-
-    echo '{"experimental": true, "ip6tables": true, "live-restore": true}' > /etc/docker/daemon.json
-    systemctl stop docker
-    systemctl start docker
+Run the following commands to configure Docker for IPv6 and Live restore and to install required dependencies, setup Docker Apt repository, and install Docker:
+
+    mkdir -p /etc/docker && \
+    echo '{"ip6tables": true, "live-restore": true}' > /etc/docker/daemon.json && \
+    apt update && \
+    apt install -yqq --no-install-recommends --no-install-suggests ca-certificates curl jq gnupg && \
+    install -m 0755 -d /etc/apt/keyrings && \
+    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o - > /etc/apt/keyrings/docker.gpg && \
+    chmod a+r /etc/apt/keyrings/docker.gpg && \
+    echo -e "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
+    https://download.docker.com/linux/"$(. /etc/os-release && echo "$ID $VERSION_CODENAME")" stable\n \
+    deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
+    https://download.docker.com/linux/"$(. /etc/os-release && echo "$ID $VERSION_CODENAME")" test" \
+    > /etc/apt/sources.list.d/docker.list && apt update && \
+    apt install -yqq --no-install-recommends --no-install-suggests docker-ce
 
 ## Application setup
 
@@ -127,7 +119,7 @@ This command should complete without an error, indicating the application stack
 
 Create database indexes:
 
-    docker compose --project-name=internetnl-prod exec app ./manage.py api_create_db_indexes
+    /opt/Internet.nl/docker/compose.sh exec app ./manage.py api_create_db_indexes
 
 ## DNS setup
 
@@ -169,9 +161,9 @@ Please see the generic troubleshooting documentation in [Deployment#Troubleshoot
 If batch jobs seem to be stuck, check the `Batch` dashboard in Grafana (see [Deployment#Grafana](Docker-deployment.md#metrics-grafanaprometheus)). The `Individual task completion rate` graph should show a variaty of tasks being completed per second. If this graph is empty or shows gaps this might indicate the batch jobs got stuck in a deadlock. In this case bring down the environment, remove the Redis and RabbitMQ volumes and start the environment again:
 
     cd /opt/Internet.nl
-    docker compose --project-name=internetnl-prod down
+    /opt/Internet.nl/docker/compose.sh down
     docker volume rm internetnl-prod_rabbitmq
     docker volume rm internetnl-prod_redis
-    env -i docker compose --env-file=docker/defaults.env --env-file=docker/host.env --env-file=docker/local.env up --wait --no-build
+    env -i /opt/Internet.nl/docker/compose.sh up --wait --no-build
 
 This issue can happen on rare occasions, is you encounter this persistently please create an issue in the Internet.nl repository: https://github.com/internetstandards/Internet.nl/issues/new
diff --git a/documentation/Docker-deployment.md b/documentation/Docker-deployment.md
@@ -38,68 +38,21 @@ A public domain name or subdomain is required. It should be possible to set the
 
 After installation and basic configuration of the OS switch to `root` user.
 
-Currently some Docker and Compose versions cause issues during setup (see: `documentation/Docker-getting-started.md#Prerequisites`). The following command will install a file that will prevent installing unsupported versions:
-
-    cat > /etc/apt/preferences.d/internetnl-docker-supported-versions <<EOF
-    # prevent installation of unsupported versions of Docker/Compose
-    # https://github.com/internetstandards/Internet.nl/pull/1419
-    Package: docker-ce
-    Pin: version 5:25.*
-    Pin-priority: -1
-
-    Package: docker-ce
-    Pin: version 5:26.0.*
-    Pin-priority: -1
-
-    Package: docker-ce
-    Pin: version 5:26.1.0-*
-    Pin-priority: -1
-
-    Package: docker-ce
-    Pin: version 5:26.1.1-*
-    Pin-priority: -1
-
-    Package: docker-ce
-    Pin: version 5:26.1.2-*
-    Pin-priority: -1
-
-    Package: docker-compose-plugin
-    Pin: version 2.24.*
-    Pin-priority: -1
-
-    Package: docker-compose-plugin
-    Pin: version 2.25.*
-    Pin-priority: -1
-
-    Package: docker-compose-plugin
-    Pin: version 2.26.*
-    Pin-priority: -1
-
-    Package: docker-compose-plugin
-    Pin: version 2.27.1-*
-    Pin-priority: -1
-    EOF
-
-Run the following command to install required dependencies, setup Docker Apt repository, and install Docker:
-
+Run the following commands to configure Docker for IPv6 and Live restore and to install required dependencies, setup Docker Apt repository, and install Docker:
 
+    mkdir -p /etc/docker && \
+    echo '{"ip6tables": true, "live-restore": true}' > /etc/docker/daemon.json && \
     apt update && \
-    apt install -yqq ca-certificates curl jq gnupg && \
+    apt install -yqq --no-install-recommends --no-install-suggests ca-certificates curl jq gnupg && \
     install -m 0755 -d /etc/apt/keyrings && \
-    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
+    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o - > /etc/apt/keyrings/docker.gpg && \
     chmod a+r /etc/apt/keyrings/docker.gpg && \
     echo -e "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
     https://download.docker.com/linux/"$(. /etc/os-release && echo "$ID $VERSION_CODENAME")" stable\n \
     deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] \
     https://download.docker.com/linux/"$(. /etc/os-release && echo "$ID $VERSION_CODENAME")" test" \
     > /etc/apt/sources.list.d/docker.list && apt update && \
-    apt install -yqq docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-
-Configure Docker for IPv6 and Live restore:
-
-    echo '{"experimental": true, "ip6tables": true, "live-restore": true}' > /etc/docker/daemon.json && \
-    systemctl stop docker && \
-    systemctl start docker
+    apt install -yqq --no-install-recommends --no-install-suggests docker-ce
 
 ## Application setup
 
@@ -177,15 +130,19 @@ After deployment is complete, all services are healthy and DNS is setup you can
 
 For more information see: [documentation/Docker-live-tests.md](Docker-live-tests.md)
 
+## Compose command
+
+To reduce issues with different versions a Compose command is included in the installation and can be accessed using `/opt/Internet.nl/docker/compose.sh`. Use this command for everything where you would normaly use `docker compose` to manage the Compose project.
+
 ## Logging
 
 Log output from containers/services can be obtained using the following command:
 
-    docker compose --project-name=internetnl-prod logs -f
+    /opt/Internet.nl/docker/compose.sh logs -f
 
 Or only for specific services:
 
-    docker compose --project-name=internetnl-prod logs -f app
+    /opt/Internet.nl/docker/compose.sh logs -f app
 
 These same logs are also sent to the `journald` daemon to be logged by the OS. This can then be used to forward to remote logging, etc.
 
@@ -205,11 +162,11 @@ By default task start and completion is not logged. To enable this set the `CELE
 
 When things don't seem to be working as expected and the logs don't give clear indications of the cause the first thing to do is check the status of the running containers/services:
 
-    docker compose --project-name=internetnl-prod  ps -a
+    /opt/Internet.nl/docker/compose.sh  ps -a
 
 Or use this command to omit the `COMMAND` and `PORTS` columns for a more compact view with only relevant information:
 
-    docker compose --project-name=internetnl-prod  ps -a --format "table {{.Name}}\t{{.Image}}\t{{.Service}}\t{{.RunningFor}}\t{{.Status}}"
+    /opt/Internet.nl/docker/compose.sh  ps -a --format "table {{.Name}}\t{{.Image}}\t{{.Service}}\t{{.RunningFor}}\t{{.Status}}"
 
 Containers/services should have a `STATUS` of `Up` and there should be no containers/services with `unhealthy`. The `db-migrate` having status `Exited (0)` is expected. Containers/services with a short uptime (seconds/minutes) might indicate it restarted recently due to an error.
 
@@ -219,12 +176,12 @@ If a container/service is not up and healthy the cause might be deduced by inspe
 
 It might be possible not all containers that should be running are running. To have Docker Compose check the running instance and bring up any missing components run:
 
-    env -i docker compose --env-file=docker/defaults.env --env-file=docker/host.env --env-file=docker/local.env up --wait --no-build
+    env -i /opt/Internet.nl/docker/compose.sh up --wait --no-build
 
 If this does not solve the issue you might want to reset the instance by bringing everything down and up again:
 
-    docker compose --project-name=internetnl-prod down
-    env -i docker compose --env-file=docker/defaults.env --env-file=docker/host.env --env-file=docker/local.env up --wait --no-build
+    /opt/Internet.nl/docker/compose.sh down
+    env -i /opt/Internet.nl/docker/compose.sh up --wait --no-build
 
 If this does not work problems might lay deeper and OS level troubleshooting might be required.
 
@@ -242,7 +199,7 @@ Docker Compose relies on an internal DNS resolver to resolve container/services
 
 The issue can be resolved by restarting the application:
 
-    docker compose --project-name=internetnl-prod restart
+    /opt/Internet.nl/docker/compose.sh restart
 
 ## Updating
 
@@ -280,11 +237,11 @@ This variable can be set to either of these values:
 
 Auto upgrades are performed by the `cron-docker` container/service. Progress/errors can be viewed by inspecting the container's logs:
 
-    docker compose --project-name=internetnl-prod logs --follow cron-docker
+    /opt/Internet.nl/docker/compose.sh logs --follow cron-docker
 
 To manually kick off the update process use the following command:
 
-    docker compose --project-name=internetnl-prod exec cron-docker /etc/periodic-docker/15min/auto_update
+    /opt/Internet.nl/docker/compose.sh exec cron-docker /etc/periodic-docker/5min/auto_update
 
 **notice**: the update logging might be cut-off at the end because the `cron-docker` container/service will be restarted in the process.
 
@@ -313,11 +270,11 @@ In essence downgrading is the same procedure as upgrading. For example, to roll
 
 By default the installation will try to request a HTTPS certificate with Letsencrypt for the domain and it's subdomains. If this is not possible it will fall back to a self-signed 'localhost' certificate. If requesting a certificate fails you can debug it by viewing the logs using:
 
-    docker compose --project-name=internetnl-prod logs webserver
+    /opt/Internet.nl/docker/compose.sh logs webserver
 
 and
 
-    docker compose --project-name=internetnl-prod exec webserver cat /var/log/letsencrypt/letsencrypt.log
+    /opt/Internet.nl/docker/compose.sh exec webserver cat /var/log/letsencrypt/letsencrypt.log
 
 It may take a few minutes after starting for the Letsencrypt certificates to be registered and loaded.
 
@@ -405,7 +362,7 @@ Current alert status can seen at: https://example.com/prometheus/alerts or https
 
 If notification emails are not being sent even though alert status shows red see Alertmanager logging for debugging:
 
-    docker compose --project-name=internetnl-prod logs --follow alertmanager
+    /opt/Internet.nl/docker/compose.sh logs --follow alertmanager
 
 ## Restricting access
 
@@ -437,7 +394,7 @@ When adding both users and IPs in `ALLOW_LIST`, users connecting from an IP in t
 
 After changing the IP or hostname in the `docker/host.env` file run:
 
-    env -i docker compose --env-file=docker/defaults.env --env-file=docker/host.env --env-file=docker/local.env up --wait --no-build
+    env -i /opt/Internet.nl/docker/compose.sh up --wait --no-build
 
 to update the DNSSEC accordingly.
 
diff --git a/documentation/Docker-getting-started.md b/documentation/Docker-getting-started.md
@@ -4,18 +4,14 @@ This documented is intended as a quick simple guide to setup a development envir
 
 ## Prerequisites
 
-An OCI compatible container runtime with [Compose V2](https://docs.docker.com/compose/migrate/) is required to run the project. For example one of the following:
+An OCI compatible container runtime (Docker) with a recent [Compose](https://github.com/docker/compose) is required to run the project. For example one of the following:
 
 - [Docker](https://docs.docker.com/get-docker/) for Linux, (supported)
 - [Colima](https://github.com/abiosoft/colima) for Mac (recommended)
-- [OrbStack](https://orbstack.dev/download) for Mac (non open source, free, tested version 1.10.2)
+- [OrbStack](https://orbstack.dev/download) for Mac (non open source, free, tested version 2.0.5)
 - [Docker](https://docs.docker.com/get-docker/) for Mac (supported)
 - [Docker](https://docs.docker.com/get-docker/) for Windows (untested)
 
-**notice**: some versions of Docker Engine might experience issues with internal DNS resolving and will cause tests to fail. Versions from and including `25.0.5` to and including `26.1.2` should be avoided.
-
-**notice**: Docker Compose Plugin versions below and up to `2.27.2` should be avoided due to missing features.
-
 **notice**: your Docker runtime should be configured with enough memory and CPU, otherwise the environment will be unstable. Minimum is at least 4GB memory and 2 CPU cores, more is better for quicker rebuild/restart of images/containers.
 
 **for arm users (eg apple m1)**: nassl will not compile on x64 architectures, so use the option to start your container engine in x86 mode. For colima this can be done with `colima start --arch x86_64`. As per the system requirements noted above, the right way to start with colima would then be: `colima start --arch x86_64 --cpu 2 --memory 4`, but giving it some room would make that: `colima start --arch x86_64 --cpu 4 --memory 8`.
diff --git a/documentation/Docker-multi-deployment.md b/documentation/Docker-multi-deployment.md
