How do I use Docker Compose on an Ubuntu or Debian VPS?
Write a compose.yaml file, start WordPress and MariaDB with docker compose up -d, then manage logs, updates, backups and HTTPS on a Linux VPS.
Docker Compose describes several containers in a single file, compose.yaml: images, ports, volumes, variables and start order. One command, docker compose up -d, creates or updates the whole stack. This guide starts from a VPS where Docker is already installed, builds a real example, WordPress with MariaDB, then covers the everyday commands and the most common errors. It applies as is to Ubuntu 22.04 / 24.04 and Debian 12 / 13.
Step-by-step procedure
-
Check Docker and the Compose plugin
Run docker compose version. If the answer is docker: 'compose' is not a docker command, install Docker from the official repository with the docker-compose-plugin package, as in the Docker installation guide.
-
Create the project folder
Create one folder per application, for example /opt/wordpress, and move into it. Compose names the project after this folder and looks for compose.yaml in the current folder.
-
Write the .env file and compose.yaml
Generate a password in .env, readable by root only, then copy the compose.yaml file below. At startup, Compose replaces ${DB_PASSWORD} with the value read from .env.
-
Start the stack
Run docker compose up -d. Compose pulls the images, creates the network and the volumes, waits until MariaDB is ready, then starts WordPress. docker compose ps then shows both services as Up, with (healthy) for db.
-
Test and read the logs
From the VPS, curl -I http://127.0.0.1:8080 should return a redirect to the WordPress installation page. If something goes wrong, docker compose logs -f --tail=100 shows the logs of all services.
-
Update the containers
To move to a new version, change the image tag in compose.yaml, then run docker compose pull and docker compose up -d: only the containers whose image or configuration changed are recreated, and the volumes stay in place.
Create the project and its password
mkdir -p /opt/wordpress
cd /opt/wordpress
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env
compose.yaml file: WordPress and MariaDB
services:
db:
image: mariadb:11.4
restart: unless-stopped
environment:
MARIADB_DATABASE: wordpress
MARIADB_USER: wordpress
MARIADB_PASSWORD: ${DB_PASSWORD}
MARIADB_RANDOM_ROOT_PASSWORD: "1"
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 5
wordpress:
image: wordpress:6.8-apache
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
WORDPRESS_DB_HOST: db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
WORDPRESS_DB_NAME: wordpress
ports:
- "127.0.0.1:8080:80"
volumes:
- wp_data:/var/www/html
volumes:
db_data:
wp_data:
Start and check
docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs -f --tail=100
Everyday Docker Compose commands
docker compose ps
docker compose logs --tail=50 wordpress
docker compose restart wordpress
docker compose exec db sh
docker compose stop
docker compose start
docker compose down
docker compose config --quiet
docker compose ls
Update the images
cd /opt/wordpress
docker compose pull
docker compose up -d
docker image prune -f
Back up the MariaDB database
cd /opt/wordpress
docker compose exec -T db sh -c 'mariadb-dump -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > wordpress-$(date +%F).sql
HTTPS with Caddy: compose.override.yaml
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
Caddyfile
example.com {
reverse_proxy wordpress:80
}
Before you start
You need a Linux VPS with Docker Engine and the Compose plugin, installed from Docker’s official repository: follow the guide “How do I install Docker on Debian 12 or Ubuntu 24.04?” if you have not done so yet. The commands are run as root; an account in the docker group can also run them without sudo.
- Compose v2 is written docker compose, with a space. The old docker-compose program (v1) has not been maintained since 2023: do not install it with pip or apt.
- The file is called compose.yaml; docker-compose.yml is still read for older projects. The version: line at the top of the file is obsolete and no longer does anything.
- WordPress and MariaDB fit in 1 to 2 GB of RAM; plan for more as soon as several stacks run on the same VPS.
Understanding the compose.yaml file
Each entry under services becomes a container. Compose also creates a private network for the project: services reach each other by name, hence WORDPRESS_DB_HOST: db. No MariaDB port is published, so the database stays invisible from the Internet.
- image: the image and its tag. Pin a version (mariadb:11.4) rather than latest so you know what you are updating.
- ports: "127.0.0.1:8080:80" publishes container port 80 on port 8080 of the VPS, locally only. Without 127.0.0.1, the port is open to the Internet, even if UFW blocks it.
- volumes: a named volume (db_data) keeps the data when the container is recreated. It is only deleted by docker compose down -v or docker volume rm.
- environment and .env: secrets stay in .env, outside the file you share or put under version control.
- restart: unless-stopped restarts the containers after a crash or a VPS reboot, except those you stopped by hand.
- depends_on with condition: service_healthy waits for the MariaDB healthcheck to pass before starting WordPress.
Putting the site online over HTTPS
To serve the site on a domain name, point an A record to the VPS’s IPv4 address, open ports 80 and 443, then add Caddy in a compose.override.yaml file, which Compose reads automatically along with compose.yaml. Replace example.com with your domain in the Caddyfile: Caddy obtains and renews the Let’s Encrypt certificate on its own.
Then finish the WordPress installation from your domain’s https address, not from 127.0.0.1: WordPress saves the address used during installation.
Backups and updates of the stack
A volume is not a backup: it disappears with the VPS or with a down -v run by mistake. Export the database with mariadb-dump (block above), copy the project folder and the contents of the volumes, then send everything off the VPS.
- docker compose pull downloads the new images for the given tags, docker compose up -d recreates the affected containers and docker image prune -f frees the space used by the old images.
- Before moving to a new major version of MariaDB or PostgreSQL, take an SQL export: the new version may require a data migration.
- docker system df shows the space used by images, containers and volumes.
Which VPS for Docker Compose?
Docker needs a real Linux kernel: a KVM VPS works, shared hosting does not. At ACLClouds, as of 16 November 2026, the VPS Mini (2 vCPU, 8 GB of RAM, 40 GB of storage) costs €4.99 per month with no commitment, or €3.99 per month with a one-year commitment: it runs several small Compose stacks. The VPS Essentiel (4 vCPU, 16 GB of RAM, 80 GB), at €9.99 per month, suits a busy database or n8n alongside a website.
The -v option of docker compose down erases data
docker compose down -v also deletes the project’s named volumes, and with them the MariaDB database and the WordPress files. Take an export before any command with -v.
Quick check
- docker compose version answers without an error.
- docker compose ps shows db as (healthy) and wordpress as Up.
- Port 8080 is only published on 127.0.0.1.
- .env is in mode 600 and is not in any Git repository.
- A recent SQL export is stored off the VPS.
Frequently asked questions
Why do I get no configuration file provided: not found?
Compose finds neither compose.yaml nor docker-compose.yml in the current folder. Move into the project folder with cd /opt/wordpress, or point to the file with docker compose -f /opt/wordpress/compose.yaml up -d.
Compose shows “the attribute version is obsolete”: is it serious?
No, it is just a warning. Compose v2 ignores the version: "3.8" line at the top of the file: delete it to make the warning go away, the rest of the file stays the same.
Why do I get port is already allocated or address already in use at startup?
Another container already publishes that port, or a service on the VPS (nginx, Apache) is listening on it. Find it with docker ps --filter publish=80 and ss -tlnp | grep :80, then stop it or change the left-hand port in ports, for example "8081:80".
Why do I get docker: 'compose' is not a docker command?
The Compose v2 plugin is not installed. With Docker’s official repository, run apt install docker-compose-plugin. The docker.io and docker-compose packages from the distributions are out of date or only provide the old hyphenated command.
Why are my changes to compose.yaml not taken into account?
docker compose restart restarts the containers without reading the file again. Run docker compose up -d: Compose compares the configuration and recreates the services that changed. Check the file first with docker compose config.
Has my data gone after docker compose down?
No: docker compose down removes the containers and the network, not the named volumes. Data only disappears with down -v, or if it was written inside the container without a volume. docker volume ls lists the volumes, prefixed with the project name, for example wordpress_db_data.
How do I fix yaml: line 8: mapping values are not allowed in this context?
The YAML file is badly indented: a tab instead of spaces, or a level out of place. Use spaces only (two per level), put values that contain :, such as ports, in quotes, then check with docker compose config.