ACLClouds
ACLClouds

Come usare Docker Compose su un VPS Ubuntu o Debian?

Scrivere un file compose.yaml, avviare WordPress e MariaDB con docker compose up -d, poi gestire log, aggiornamenti, backup e HTTPS su un VPS Linux.

Docker Compose descrive più container in un unico file, compose.yaml: immagini, porte, volumi, variabili e ordine di avvio. Un solo comando, docker compose up -d, crea o aggiorna l’intero stack. Questa guida parte da un VPS con Docker già installato, costruisce un esempio concreto, WordPress con MariaDB, poi spiega i comandi di tutti i giorni e gli errori più comuni. Vale così com’è per Ubuntu 22.04 / 24.04 e Debian 12 / 13.

Procedura passo passo

  1. Verifica Docker e il plugin Compose

    Esegui docker compose version. Se la risposta è docker: 'compose' is not a docker command, installa Docker dal repository ufficiale con il pacchetto docker-compose-plugin, come nella guida all’installazione di Docker.

  2. Crea la cartella del progetto

    Crea una cartella per applicazione, per esempio /opt/wordpress, ed entra al suo interno. Compose dà al progetto il nome di questa cartella e cerca compose.yaml nella cartella corrente.

  3. Scrivi il file .env e compose.yaml

    Genera una password in .env, leggibile solo da root, poi copia il file compose.yaml qui sotto. All’avvio, Compose sostituisce ${DB_PASSWORD} con il valore letto in .env.

  4. Avvia lo stack

    Esegui docker compose up -d. Compose scarica le immagini, crea la rete e i volumi, attende che MariaDB sia pronta, poi avvia WordPress. docker compose ps mostra quindi i due servizi in Up, con (healthy) per db.

  5. Testa e leggi i log

    Dal VPS, curl -I http://127.0.0.1:8080 deve restituire un reindirizzamento alla pagina di installazione di WordPress. In caso di problemi, docker compose logs -f --tail=100 mostra i log di tutti i servizi.

  6. Aggiorna i container

    Per passare a una nuova versione, cambia il tag dell’immagine in compose.yaml, poi esegui docker compose pull e docker compose up -d: vengono ricreati solo i container la cui immagine o configurazione è cambiata, i volumi restano al loro posto.

Creare il progetto e la sua password

mkdir -p /opt/wordpress
cd /opt/wordpress
echo "DB_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env

File compose.yaml: WordPress e 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:

Avviare e verificare

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8080
docker compose logs -f --tail=100

Comandi Docker Compose di tutti i giorni

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

Aggiornare le immagini

cd /opt/wordpress
docker compose pull
docker compose up -d
docker image prune -f

Fare il backup del database MariaDB

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 con 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
}

Prima di iniziare

Ti serve un VPS Linux con Docker Engine e il plugin Compose, installati dal repository ufficiale di Docker: segui la guida « Come installare Docker su Debian 12 o Ubuntu 24.04? » se non l’hai ancora fatto. I comandi vanno eseguiti come root; un account membro del gruppo docker può eseguirli anche senza sudo.

  • Compose v2 si scrive docker compose, con uno spazio. Il vecchio programma docker-compose (v1) non è più mantenuto dal 2023: non installarlo né con pip né con apt.
  • Il file si chiama compose.yaml; docker-compose.yml viene ancora letto per i progetti più vecchi. La riga version: all’inizio del file è obsoleta e non serve più a nulla.
  • WordPress e MariaDB stanno in 1-2 GB di RAM; prevedi di più non appena girano più stack sullo stesso VPS.

Capire il file compose.yaml

Ogni voce di services diventa un container. Compose crea anche una rete privata per il progetto: i servizi si raggiungono lì tramite il loro nome, da cui WORDPRESS_DB_HOST: db. Nessuna porta di MariaDB viene pubblicata, quindi il database resta invisibile da Internet.

  • image: l’immagine e il suo tag. Fissa una versione (mariadb:11.4) invece di latest per sapere cosa stai aggiornando.
  • ports: "127.0.0.1:8080:80" pubblica la porta 80 del container sulla porta 8080 del VPS, solo in locale. Senza 127.0.0.1, la porta è aperta su Internet, anche se UFW la blocca.
  • volumes: un volume con nome (db_data) conserva i dati quando il container viene ricreato. Viene eliminato solo da docker compose down -v o docker volume rm.
  • environment e .env: i segreti restano in .env, fuori dal file che condividi o metti sotto controllo di versione.
  • restart: unless-stopped riavvia i container dopo un crash o un riavvio del VPS, tranne quelli che hai fermato a mano.
  • depends_on con condition: service_healthy attende che l’healthcheck di MariaDB riesca prima di avviare WordPress.

Mettere il sito online in HTTPS

Per servire il sito su un nome di dominio, punta un record A sull’IPv4 del VPS, apri le porte 80 e 443, poi aggiungi Caddy in un file compose.override.yaml, che Compose legge automaticamente insieme a compose.yaml. Sostituisci example.com con il tuo dominio nel Caddyfile: Caddy ottiene e rinnova da solo il certificato Let’s Encrypt.

Completa poi l’installazione di WordPress dall’indirizzo https del tuo dominio, non da 127.0.0.1: WordPress registra l’indirizzo usato durante l’installazione.

Backup e aggiornamenti dello stack

Un volume non è un backup: sparisce con il VPS o con un down -v lanciato per errore. Esporta il database con mariadb-dump (blocco qui sopra), copia la cartella del progetto e il contenuto dei volumi, poi invia tutto fuori dal VPS.

  • docker compose pull scarica le nuove immagini dei tag indicati, docker compose up -d ricrea i container interessati e docker image prune -f libera lo spazio delle vecchie immagini.
  • Prima di passare a una nuova versione principale di MariaDB o PostgreSQL, fai un export SQL: la nuova versione può richiedere una migrazione dei dati.
  • docker system df indica lo spazio occupato da immagini, container e volumi.

Quale VPS per Docker Compose?

Docker ha bisogno di un vero kernel Linux: un VPS KVM va bene, un hosting condiviso no. Su ACLClouds, al 16 novembre 2026, il VPS Mini (2 vCPU, 8 GB di RAM, 40 GB di spazio) costa 4,99 € al mese senza vincolo, oppure 3,99 € al mese con un impegno di un anno: fa girare diversi piccoli stack Compose. Il VPS Essentiel (4 vCPU, 16 GB di RAM, 80 GB), a 9,99 € al mese, è adatto a un database molto sollecitato o a n8n accanto a un sito.

L’opzione -v di docker compose down cancella i dati

docker compose down -v elimina anche i volumi con nome del progetto, quindi il database MariaDB e i file di WordPress. Fai un export prima di qualsiasi comando con -v.

Verifica rapida

  • docker compose version risponde senza errori.
  • docker compose ps mostra db in (healthy) e wordpress in Up.
  • La porta 8080 è pubblicata solo su 127.0.0.1.
  • .env ha i permessi 600 e non si trova in nessun repository Git.
  • Un export SQL recente è conservato fuori dal VPS.

Domande frequenti

Perché compare no configuration file provided: not found?

Compose non trova né compose.yaml né docker-compose.yml nella cartella corrente. Entra nella cartella del progetto con cd /opt/wordpress, oppure indica il file con docker compose -f /opt/wordpress/compose.yaml up -d.

Compose mostra « the attribute version is obsolete »: è grave?

No, è un semplice avviso. Compose v2 ignora la riga version: "3.8" all’inizio del file: eliminala per farlo sparire, il resto del file non cambia.

Perché compare port is already allocated o address already in use all’avvio?

Un altro container pubblica già quella porta, oppure un servizio del VPS (nginx, Apache) è in ascolto su di essa. Trovalo con docker ps --filter publish=80 e ss -tlnp | grep :80, poi fermalo o cambia la porta di sinistra in ports, per esempio "8081:80".

Perché compare docker: 'compose' is not a docker command?

Il plugin Compose v2 non è installato. Con il repository ufficiale di Docker, esegui apt install docker-compose-plugin. I pacchetti docker.io e docker-compose delle distribuzioni sono indietro oppure forniscono solo il vecchio comando con il trattino.

Perché le mie modifiche a compose.yaml non vengono applicate?

docker compose restart riavvia i container senza rileggere il file. Esegui docker compose up -d: Compose confronta la configurazione e ricrea i servizi modificati. Verifica prima il file con docker compose config.

I miei dati sono spariti dopo docker compose down?

No: docker compose down elimina i container e la rete, non i volumi con nome. I dati spariscono solo con down -v, o se venivano scritti nel container senza volume. docker volume ls elenca i volumi, con il nome del progetto come prefisso, per esempio wordpress_db_data.

Cosa correggere dopo yaml: line 8: mapping values are not allowed in this context?

Il file YAML è indentato male: una tabulazione al posto degli spazi, oppure un livello spostato. Usa solo spazi (due per livello), metti tra virgolette i valori che contengono : come le porte, poi verifica con docker compose config.