# Docker-compose Update Module
**URL:** https://hub.mender.io/t/docker-compose-update-module/8218
**Category:** Update Modules
**Created:** [March 25, 2026, 12:25pm UTC](https://hub.mender.io/t/docker-compose-update-module/8218 "2026-03-25T12:25:32Z")
**Posts on this page:** 1
**Page:** 1
### Author:  [@danieldrabitzius](https://hub.mender.io/u/danieldrabitzius)
#### Post date: [March 25, 2026, 12:25pm UTC](https://hub.mender.io/t/docker-compose-update-module/8218/1 "2026-03-25T12:25:32Z")
### 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](https://github.com/mendersoftware/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](https://docs.mender.io/downloads/workstation-tools#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](https://docs.mender.io/operating-system-updates-debian-family/customize-mender/docker-compose-support).
## Installation with Yocto
For instructions on installation with Yocto, see [Mender Docs](https://docs.mender.io/operating-system-updates-yocto-project/customize-mender/docker-compose-update-module).
## Preparing images and Artifacts
#### Install the Artifact generator
Download the Artifact generator from the repository:
```bash
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:
```bash
./gen_docker-compose --help
```
See [Create a docker-compose update Artifact](https://docs.mender.io/artifact-creation/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:
```bash
mkdir -p manifests
cat > manifests/docker-compose.yml <<'EOF'
services:
web:
image: busybox
ports:
- "8080:80"
command: >
sh -c "mkdir -p /www && echo 'Version 1.0
' > /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:
```bash
./gen_docker-compose \
--list-architectures \
--manifests-dir manifests/
```
This will output something like:
```bash
busybox: 386,amd64,arm,arm64,ppc64le,riscv64,s390x
```
Specify the architecture of your device:
```bash
ARCHITECTURE=
```
Set the Device type:
```bash
DEVICE_TYPE=
```
Now we’ll create the Mender Artifact:
```bash
./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:
```auto
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:
```bash
cat > manifests/docker-compose.yml <<'EOF'
services:
web:
image: busybox
ports:
- "8080:80"
command: >
sh -c "mkdir -p /www && echo 'Version 2.0
' > /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:
```bash
./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:
```bash
cat > manifests/docker-compose.yml <<'EOF'
services:
web:
image: busybox
ports:
- "8080:80"
command: >
sh -c "mkdir -p /www && echo 'Version 3.0
' > /www/index.html"
healthcheck:
test: ["CMD", "wget", "-q", "-O-", "http://localhost/"]
interval: 10s
timeout: 5s
retries: 3
EOF
```
```bash
./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”.