Docker and Docker Compose on a VPS: installation and your first app

Docker runs apps in isolated containers that bring everything they need with them. We'll install it from the official repository, use Docker Compose to run WordPress with a database, and go through management, updates, the firewall and backups.

How it works#

Installation#

Install Docker from Docker's official repository. The docker.io package from the distribution repository tends to be older and conflicts with the official packages.

First remove any conflicting packages. On a fresh VPS the command finds nothing, which is fine.

• dpkg --get-selections … – lists which of the given packages are installed.
• | cut -f1 – keeps only the package names.
• apt remove $(…) – uninstalls them. Data in /var/lib/docker stays.

Then add the Docker repository and install Docker:

What each line does:

After installation Docker starts on its own and is enabled at VPS boot. Check the installation:

docker run --rm hello-world
docker compose version

• docker run --rm hello-world – downloads a test image and runs it; --rm deletes the container when it finishes. You'll see Hello from Docker!.
• docker compose version – prints the Compose version, for example Docker Compose version v5.…. After version 2, Compose jumped straight to 5, so older installations show v2.…. The commands in this guide work with both.

First app: WordPress with MariaDB#

Project and passwords#

1. Create the project directory and switch to it:

   mkdir -p /opt/wordpress
   cd /opt/wordpress

   The directory name (wordpress) becomes the Compose project name and the prefix for container and volume names.

2. Create a file with the passwords using nano .env. Generate the passwords with the password generator (letters and digits only):

   DB_PASSWORD=<DATABASE_PASSWORD>
   DB_ROOT_PASSWORD=<DATABASE_ROOT_PASSWORD>

   • DB_PASSWORD – password of the WordPress database user.
   • DB_ROOT_PASSWORD – password of the root user inside the database container (for backups and administration).

3. Make the file readable by root only:

   chmod 600 .env

The compose.yaml file#

Create nano compose.yaml with this content:

services:
  db:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

  wordpress:
    image: wordpress:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html

volumes:
  db_data:
  wp_data:

Line by line:

Starting it#

docker compose up -d
docker compose ps

• docker compose up -d – downloads the images, creates the network, volumes and containers and starts them in the background (-d, detached).
• docker compose ps – lists the project's containers and their status. db shows healthy, wordpress shows Up.

Check from the VPS: curl -I http://127.0.0.1:8080 returns WordPress's response headers (a redirect to the installer).

Exposing it through Nginx and HTTPS#

WordPress now listens only on 127.0.0.1:8080. Expose it through Nginx as a reverse proxy following the Nginx and HTTPS guide: in the configuration use proxy_pass http://127.0.0.1:8080; and your domain, for example blog.example.cz, then get a certificate with certbot --nginx -d blog.example.cz.

The WordPress image detects HTTPS on its own from the X-Forwarded-Proto header, which Nginx sends when set up as in that guide. Finally, open https://blog.example.cz and finish the WordPress installation in your browser.

Managing containers#

Run docker compose commands in the project directory (cd /opt/wordpress).

Updating to new image versions:

docker compose pull
docker compose up -d
docker image prune -f

• docker compose pull – downloads new image versions.
• docker compose up -d – recreates containers that have a newer image. Data in volumes stays.
• docker image prune -f – deletes old images that are no longer used; -f skips the confirmation.

Options for restart::

Ports and the firewall#

Docker publishes container ports with its own firewall rules that bypass UFW. A port published as 8080:80 is reachable from the internet even if you don't allow it in UFW. The UFW firewall guide explains this in detail.

Don't publish databases and other internal services at all. Restrict ports that need to be public (for example a game server in a container) with the firewall in the customer area (guide). It sits in front of the VPS and Docker can't bypass it.

Freeing up disk space#

Images, stopped containers and logs take up a lot of space over time.

docker system df
docker system prune

• docker system df – how much space images, containers, volumes and the cache take.
• docker system prune – after confirmation, deletes stopped containers, unused networks, untagged images and the build cache. It doesn't delete volumes with data unless you add --volumes.

By default, container logs aren't rotated and can fill up the disk. Set the local driver, which removes old logs on its own (by default it keeps at most 5 files of 20 MB per container). Create the file nano /etc/docker/daemon.json with the content below. If the file already exists, don't overwrite it; just add the "log-driver" line (entries separated by commas):

{
  "log-driver": "local"
}

Then restart Docker (systemctl restart docker) and recreate the containers (docker compose up -d --force-recreate). The setting only applies to newly created containers.

Backups#

Back up volumes, not containers. You can recreate a container from its image, but not the data.

1. Create a directory for backups: mkdir -p /root/zalohy.

2. Back up the database with an export (more consistent than copying files):

   cd /opt/wordpress
   docker compose exec -T db sh -c 'exec mariadb-dump --single-transaction --all-databases -uroot -p"$MARIADB_ROOT_PASSWORD"' > /root/zalohy/wp-db-$(date +%F).sql

   • docker compose exec -T db – runs a command in the db container; -T disables the terminal so the output can be redirected to a file.
   • sh -c '…' – the command runs in the container's shell, where the $MARIADB_ROOT_PASSWORD variable is set.
   • mariadb-dump --single-transaction --all-databases – exports all databases without locking.
   • > /root/zalohy/… – the output is saved on the VPS, outside the container.

3. Back up the WordPress files by archiving the volume:

   docker run --rm -v wordpress_wp_data:/data:ro -v /root/zalohy:/backup alpine tar czf /backup/wp-files-$(date +%F).tar.gz -C /data .

   • docker run --rm – starts a one-off container that is deleted when it finishes.
   • -v wordpress_wp_data:/data:ro – mounts the wp_data volume of the wordpress project read-only (ro).
   • -v /root/zalohy:/backup – mounts the backup directory from the VPS.
   • alpine tar czf … -C /data . – packs the volume's contents into an archive using the small Alpine image.

   docker volume ls prints the exact volume names.

Running backups automatically with cron and copying them off the VPS is covered in Backups on a VPS.

Verification#

• docker compose ps shows both containers running and the database as healthy.
• https://blog.example.cz shows WordPress with a padlock in the address bar.
• After a VPS reboot (reboot) the containers start on their own.
• From another computer you can't connect to http://<VPS_IP_ADDRESS>:8080 (the port is bound to 127.0.0.1 only).

Troubleshooting#

permission denied while trying to connect to the Docker daemon socket#

You aren't root and your user isn't in the docker group. Run the command with sudo, or log in as root.

Bind for 127.0.0.1:8080 failed: port is already allocated or address already in use#

Port 8080 is already used by another container (first message) or another program on the VPS (second message). Find out which one (ss -tlnp | grep 8080, docker ps) and pick a different port in compose.yaml, for example 127.0.0.1:8081:80. Then update proxy_pass in Nginx too.

WordPress shows “Error establishing a database connection”#

The database isn't ready yet or the credentials don't match. Check the database log (docker compose logs db). If you changed the password in .env after the first start, the database still has the old password (see the warning in Starting it).

The container keeps showing Restarting#

The app in the container crashes right after starting. You'll find the cause in the log: docker compose logs --tail 50 <SERVICE_NAME>.

toomanyrequests: You have reached your unauthenticated pull rate limit#

Docker Hub limits anonymous image pulls to 100 per 6 hours per IP address. Wait, or log in with your Docker Hub account: docker login.

no space left on device#

The disk is full. Find out what's using it (docker system df, df -h) and clean up as described in Freeing up disk space. If you're genuinely out of space, increase RAM in the Change plan tab; disk size grows with memory.

Further reading#

• Docker: Install Docker Engine on Ubuntu (opens in a new window)
• Docker: Install Docker Engine on Debian (opens in a new window)
• Docker: Packet filtering and firewalls (opens in a new window)
• Docker: Port publishing (opens in a new window)
• Docker: Compose file reference (opens in a new window)
• Docker Hub: wordpress (opens in a new window)
• Docker Hub: mariadb (opens in a new window)