Back up Docker volumes with Docker Compose and the lionbackup container
Published 30 July 2026 · 7 steps · ← Blog
How to back up Docker volumes with Docker Compose: the lionbackup client as a container without a shell, a package manager or root, encrypting your /data folder before upload. With the complete configuration, Compose file and systemd timer to copy.
Step 1: Create a project and a write token
In the portal, create a project for this server and a write token in it. A write token can only back up; it can neither read nor restore. Even if someone compromises the container and takes the token, your backups stay unreadable for them.
Note two values from the portal: the project UUID and the token. The token is shown only once.
0 (unlimited). A tight per-minute limit slows the client down exactly when it repeats a chunk after an interruption.Step 2: Create the folders on the host
The container needs three things from outside: the configuration, the public key and a working area. We create one root folder for them. The data you back up under /data stays where it is.
sudo mkdir -p /opt/lionbackup/conf /opt/lionbackup/keys
cd /opt/lionbackupThe image runs as an unprivileged user with the fixed UID 65532. So that the container can write the key pair in a moment, it owns the key folder:
sudo chown 65532:65532 /opt/lionbackup/keys| Folder | Purpose | In the container |
|---|---|---|
/data | your data, which is backed up | /data, read-only |
/opt/lionbackup/conf | the configuration file | /conf, read-only |
/opt/lionbackup/keys | key pair | /keys, read-only during operation |
| Docker volume | working area: compression and encryption happen here | /tmp |
Step 3: Generate a key pair
Encryption happens entirely on your server before anything leaves the building. For that you need a key pair. The container brings the generator along:
docker run --rm \
-v /opt/lionbackup/keys:/keys \
git.lionbackup.cloud/lionbackup/lionbackup-client:0.2.0 \
--generate-key --key-name /keys/backupAfterwards there are two files in /opt/lionbackup/keys: backup.pub is the public key and goes into the configuration next. backup.key is the private key. It is used only for a restore.
backup.key no backup can be decrypted, not by us either. We do not store it anywhere. A backup whose key only lives on the server it protects is worthless in exactly the disaster you made it for.The encryption is a post-quantum hybrid of ML-KEM-768 and X25519. Recorded ciphertext stays unreadable even if a large enough quantum computer exists in a few years.
Step 4: Write the configuration
The configuration is a single YAML file. All paths in it are paths inside the container, not on the host.
sudo tee /opt/lionbackup/conf/lionbackup.yaml >/dev/null <<'EOF'
lionbackup:
project: <project UUID from the portal>
storagezone: <storage zone of the project from the portal>
token: <write token from the portal>
# What is backed up. The host path /data is mounted as /data
# in docker-compose.yml below.
files:
- /data
compression_method: ZSTD # ZSTD (recommended), GZIP or LZMA2
compression_level: 5
# Only the PUBLIC key. The private one does not belong on this server.
encryption_keyfile: /keys/backup.pub
# Working area: the Docker volume from step 5.
tmp_directory: /tmp
chunksize: 64
log_level: INFO
EOFThe file contains a valid token and should be protected accordingly. Important: the client runs as user 65532 inside the container and only accepts a configuration with a token if nobody but its owner can read it, so that user owns the file as well:
sudo chown 65532:65532 /opt/lionbackup/conf/lionbackup.yaml
sudo chmod 600 /opt/lionbackup/conf/lionbackup.yamllog_directory is deliberately not set. Without it, the client writes its output to stdout, where the Docker logging driver collects it. That is what you want in a container setup: docker compose logs instead of a log file in a volume.
Step 5: Write docker-compose.yml
A backup is a job with a beginning and an end, not a service. So the Compose file describes a container that runs once and exits.
sudo tee /opt/lionbackup/docker-compose.yml >/dev/null <<'EOF'
services:
backup:
image: git.lionbackup.cloud/lionbackup/lionbackup-client:0.2.0
command: ["--config", "/conf/lionbackup.yaml"]
restart: "no"
# The image is a scratch image without a shell or package manager;
# it writes only to the working area below.
read_only: true
volumes:
# Source data and configuration read-only,
# working area as a named volume.
- /data:/data:ro
- ./conf:/conf:ro
- ./keys:/keys:ro
- lionbackup-tmp:/tmp
volumes:
lionbackup-tmp:
EOFTwo details are worth a second look. /data is mounted read-only: a backup program has no reason to change the data it backs up. And the working area lives on a named volume instead of a host folder. Docker takes over the folder permissions from the image, so the unprivileged user can write there without further steps.
:latest tag too, but a fixed version tag makes sure a backup run at three in the morning does not suddenly start with a different client version than the run the day before.Step 6: Start the first backup
Because the container is a one-off job, it is started with run, not up. --rm removes it afterwards.
cd /opt/lionbackup && sudo docker compose run --rm backupThe client reports its progress in three phases: checking the sources, then archiving, compressing and encrypting each source, then uploading. For larger amounts of data, a progress line with throughput and estimated remaining time appears every two seconds.
When the job finishes, the backup shows up in the portal under the latest backups. If it stops, the last line says why. The most common case during the first setup is a working area that is too small; the client then names the tmp_directory folder.
Step 7: Automate it daily
For the repetition, use a systemd timer on Linux. Unlike cron, it catches up on runs it missed because the machine was off at the scheduled time.
sudo tee /etc/systemd/system/lionbackup.service >/dev/null <<'EOF'
[Unit]
Description=lionbackup - backup of /data
After=docker.service
Requires=docker.service
[Service]
Type=oneshot
WorkingDirectory=/opt/lionbackup
ExecStart=/usr/bin/docker compose run --rm backup
EOFsudo tee /etc/systemd/system/lionbackup.timer >/dev/null <<'EOF'
[Unit]
Description=lionbackup daily at 01:00
[Timer]
OnCalendar=*-*-* 01:00:00
RandomizedDelaySec=15m
Persistent=true
[Install]
WantedBy=timers.target
EOFsudo systemctl daemon-reload
sudo systemctl enable --now lionbackup.timer
systemctl list-timers lionbackup.timerPersistent=true catches up on a missed run after the next boot. RandomizedDelaySec spreads the start by up to 15 minutes, so not all of your servers start at the same moment.
And the way back?
To restore, create a read token in the portal, have the private key ready and start the same container with --restore, --identity and --target. The steps in detail are in Restore a Windows backup from the cloud; the calls are the same on Linux.
Can we support you with the setup? Book a free appointment.