Docker-compose Update Module

Update Modules
1

Description

An Update Module to manage Docker Compose projects on a device.

This Update Module is open source. You can find the source code in mender-container-modules.

The docker-compose Update Module is available in Mender Client 6.0 and later.

Specification

Specification
Update Module name docker-compose
Supports rollback yes
Requires reboot no
Artifact generation script yes
Full operating system updater no
Source code Open source
Maintainer Northern.tech

Prerequisites

  • You have installed mender-artifact on your workstation
  • You have installed skopeo on your workstation for downloading container images from registries

The docker-compose Update Module requires the device to have Docker and Docker Compose available.

Installation on Debian systems

For instructions on installation with mender-convert, see Mender Docs.

Installation with Yocto

For instructions on installation with Yocto, see Mender Docs.

Preparing images and Artifacts

Install the Artifact generator

Download the Artifact generator from the repository:

curl -O https://raw.githubusercontent.com/mendersoftware/mender-container-modules/1.0.0/src/gen_docker-compose
chmod +x gen_docker-compose

Verify the installation:

./gen_docker-compose --help

See Create a docker-compose update Artifact in Mender Docs for more information.

Tutorial: Deployment and Automatic Rollback

This tutorial demonstrates the docker-compose Update Module with a simple web application using busybox httpd. You’ll see:

  • How to deploy an initial version
  • How to update to a new version
  • Automatic rollback when a deployment fails

Tutorial Overview

We’ll deploy three versions:

  • v1.0: Initial deployment
  • v2.0: Successful update
  • v3.0: Failed deployment that automatically rolls back to v2.0

Step 1: Create Version 1.0

Create the manifests directory and docker-compose configuration with inline HTML:

mkdir -p manifests
cat > manifests/docker-compose.yml <<'EOF'
services:
  web:
    image: busybox
    ports:
      - "8080:80"
    command: >
      sh -c "mkdir -p /www && echo '<h1>Version 1.0</h1>' > /www/index.html &&
      httpd -f -p 80 -h /www"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost/"]
      interval: 10s
      timeout: 5s
      retries: 3
EOF

By default, gen_docker-compose downloads container images for your workstation’s architecture. If your workstation differs from your device architecture, you should specify the target architecture using the --architecture flag.

First we’ll list the available architectures for the images in the manifest:

./gen_docker-compose \
    --list-architectures \
    --manifests-dir manifests/

This will output something like:

busybox: 386,amd64,arm,arm64,ppc64le,riscv64,s390x

Specify the architecture of your device:

ARCHITECTURE=<architecture>

Set the Device type:

DEVICE_TYPE=<device-type>

Now we’ll create the Mender Artifact:

./gen_docker-compose \
  --artifact-name release-v1.0 \
  --device-type "$DEVICE_TYPE" \
  --architecture "$ARCHITECTURE" \
  --output-path web-app-v1.0.mender \
  --manifests-dir manifests/ \
  --project-name web-app

The Artifact contents will look something like this:

Mender Artifact:
  Name: release-v1.0
  Format: mender
  Version: 3
  Signature: no signature
  Compatible devices: [raspberrypi5_64]
  Provides group:
  Depends on one of artifact(s): []
  Depends on one of group(s): []
  State scripts: []

Updates:
  - Type: docker-compose
    Provides:
      rootfs-image.mender-docker-compose.web-app.version: release-v1.0
    Depends: {}
    Clears Provides: [*mender-docker-compose_*]
    Metadata:
      {
        "project_name": "web-app",
        "version": "1"
      }
    Files:
      - checksum: 097f393f64635efd8d4f96ac605409180d8d9eab09bb5f6f21e0cf82071608b6
        modified: 2025-12-11 12:48:21 +0100 CET
        name: images.tar.gz
        size: 1909046
      - checksum: 9c80073679eed9f72405ea88e4524b7d98b3134f4a82084a295153852329902c
        modified: 2025-12-11 12:48:20 +0100 CET
        name: manifests.tar
        size: 10240

Upload the Artifact to Mender Server and make a deployment for release-v1.0. Once deployed, try to visit your device’s IP address in a browser. You should see “Version 1.0”.

Step 2: Create and Deploy Version 2.0

Update the Docker Compose manifest for v2.0:

cat > manifests/docker-compose.yml <<'EOF'
services:
  web:
    image: busybox
    ports:
      - "8080:80"
    command: >
      sh -c "mkdir -p /www && echo '<h1>Version 2.0</h1>' > /www/index.html &&
      httpd -f -p 80 -h /www"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost/"]
      interval: 10s
      timeout: 5s
      retries: 3
EOF

Create the Mender Artifact:

./gen_docker-compose \
  --artifact-name release-v2.0 \
  --device-type "$DEVICE_TYPE" \
  --architecture "$ARCHITECTURE" \
  --output-path web-app-v2.0.mender \
  --manifests-dir manifests/ \
  --project-name web-app

Upload and deploy the Artifact to your device. After deployment completes, refresh your browser. You should now see “Version 2.0”.

Step 3: Create Broken Version 3.0 (Rollback Demo)

Update the Docker Compose manifest for v3.0:

cat > manifests/docker-compose.yml <<'EOF'
services:
  web:
    image: busybox
    ports:
      - "8080:80"
    command: >
      sh -c "mkdir -p /www && echo '<h1>Version 3.0</h1>' > /www/index.html"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O-", "http://localhost/"]
      interval: 10s
      timeout: 5s
      retries: 3
EOF

./gen_docker-compose \
  --artifact-name release-v3.0 \
  --device-type "$DEVICE_TYPE" \
  --architecture "$ARCHITECTURE" \
  --output-path web-app-v3.0.mender \
  --manifests-dir manifests/ \
  --project-name web-app

Upload and deploy the Artifact to your device. Here’s what will happen:

  1. Mender stops the current deployment (v2.0)
  2. Mender starts the new deployment (v3.0)
  3. The composition will fail due to the healthcheck failing
  4. Mender rolls back to v2.0
  5. Your device returns to the v2.0 release

After the rollback completes, refresh your browser. You should still see “Version 2.0”.