Docker WordPress

Ambiente Docker Compose per sviluppare siti WordPress con Apache/PHP, MariaDB e Mailpit. È pensato esclusivamente per lo sviluppo locale, non per la produzione.

English version

Requisiti

• Docker Engine con il plugin Compose (docker compose)
• porte locali 8080, 3306, 1025 e 8025 disponibili, oppure porte diverse in .env

Avvio rapido

cp .env.example .env
docker compose config
docker compose up -d
docker compose ps

Apri http://localhost:8080 per installare WordPress e http://localhost:8025 per leggere le email catturate da Mailpit.

Le porte sono associate a 127.0.0.1, quindi non vengono pubblicate sulla rete locale. Modifica BIND_ADDRESS solo se ti serve esplicitamente l'accesso da un altro dispositivo.

Servizi e versioni

Servizio	Immagine predefinita	Scopo
WordPress	wordpress:7.0-php8.3-apache	applicazione web
MariaDB	mariadb:lts	database LTS supportato
Mailpit	axllent/mailpit:v1.30.0	SMTP di test e interfaccia web

Le versioni sono configurabili in .env. Prima di cambiare major version di WordPress, PHP o MariaDB verifica la compatibilità di temi e plugin ed esegui un backup. Il tag mobile mariadb:lts è comodo per nuovi ambienti di sviluppo; imposta una versione esatta se ti serve una build riproducibile nel tempo.

Variabili d'ambiente

Copia .env.example in .env e modifica i valori per il tuo ambiente. Le password sono obbligatorie: Compose interrompe l'avvio se non sono definite.

Variabile	Predefinito	Descrizione
COMPOSE_PROJECT_NAME	docker-wordpress	Nome del progetto Compose; viene usato anche come prefisso di container, rete e volumi.
BIND_ADDRESS	127.0.0.1	Indirizzo host su cui pubblicare le porte. Mantieni 127.0.0.1 per limitare l'accesso alla macchina locale.
WORDPRESS_VERSION	7.0	Versione/tag del core WordPress usato per comporre il nome dell'immagine.
PHP_VERSION	8.3	Versione PHP della variante Apache dell'immagine WordPress.
WEB_PORT	8080	Porta HTTP del sito esposta sull'host. Nel container resta la porta 80.
WORDPRESS_TABLE_PREFIX	wp_	Prefisso delle tabelle create da WordPress. Deve essere un identificatore SQL valido.
WORDPRESS_DEBUG	1	Abilita (1) o disabilita (0) WP_DEBUG. È attivo per impostazione predefinita perché lo stack è destinato allo sviluppo.
MARIADB_VERSION	lts	Tag dell'immagine MariaDB. Usa una versione esatta se vuoi un ambiente riproducibile.
DB_PORT	3306	Porta MariaDB esposta sull'host per eventuali client esterni. Tra i container viene usata sempre db:3306.
DB_NAME	wordpress	Database creato alla prima inizializzazione e usato da WordPress.
DB_USER	wordpress	Utente applicativo creato per WordPress.
DB_PASSWORD	obbligatoria	Password dell'utente applicativo. Usa un valore locale non riutilizzato altrove.
DB_ROOT_PASSWORD	obbligatoria	Password dell'utente amministratore MariaDB root.
SMTP_PORT	1025	Porta SMTP di Mailpit pubblicata sull'host. WordPress usa comunque mailpit:1025.
MAIL_UI_PORT	8025	Porta host dell'interfaccia web di Mailpit.

WP_ENVIRONMENT_TYPE è impostato direttamente dal Compose su local e non richiede una variabile in .env.

Dati e file

Important

Questo repository supporta due modalità di utilizzo di wp-content:

1. Progetto esistente o sviluppo di temi/plugin: la cartella locale wp-content/ è necessaria e deve contenere i file del progetto. Il mount ./wp-content:/var/www/html/wp-content presente in docker-compose.yml la rende disponibile nel container e permette di versionarne il codice.
2. Installazione WordPress pulita: commenta o rimuovi quel solo mount dal file Compose. Poiché wordpress_data è già montato su /var/www/html, anche wp-content verrà creata e conservata automaticamente nello stesso volume.

Non usare contemporaneamente le due posizioni per gli stessi file: il mount locale nasconde la wp-content eventualmente presente in wordpress_data. docker compose down --volumes elimina la versione contenuta nel volume, ma non quella locale. Conserva sempre una copia del codice necessario.

• per impostazione predefinita, wp-content/ è montata dal repository per temi, plugin e mu-plugin.
• il core WordPress risiede nel volume wordpress_data.
• MariaDB risiede nel volume db_data.
• i messaggi Mailpit risiedono nel volume mailpit_data.
• db/backup/ è disponibile come /backup nel container database.
• gli script in db/init/ vengono eseguiti, in ordine alfabetico, solo alla prima inizializzazione di un volume database vuoto.

I nomi effettivi dei volumi includono il valore di COMPOSE_PROJECT_NAME. Per impostazione predefinita upload, cache, log e file generati dentro wp-content/ non vengono versionati; consulta .gitignore prima di aggiungere nuove directory o eccezioni.

Email

WordPress non invia automaticamente la posta a Mailpit: configura un plugin SMTP con questi parametri:

• host: mailpit
• porta: 1025
• cifratura e autenticazione: disabilitate

La porta SMTP vista dall'host può essere cambiata con SMTP_PORT, ma tra i container resta sempre mailpit:1025.

Importazione e migrazione

Per inizializzare un nuovo ambiente da un dump, copialo in db/init/ prima del primo docker compose up. Sono accettati i formati supportati dall'immagine MariaDB, per esempio .sql, .sql.gz e script .sh eseguibili.

Per sostituire URL usa WP-CLI, che gestisce correttamente anche i dati PHP serializzati. Esempio senza installare strumenti nel container web:

docker run --rm --volumes-from "$(docker compose ps -q wordpress)" \
  --network "$(docker inspect "$(docker compose ps -q wordpress)" --format '{{range $name, $_ := .NetworkSettings.Networks}}{{$name}}{{end}}')" \
  -e WORDPRESS_DB_HOST=db:3306 \
  -e WORDPRESS_DB_USER="$(grep '^DB_USER=' .env | cut -d= -f2-)" \
  -e WORDPRESS_DB_PASSWORD="$(grep '^DB_PASSWORD=' .env | cut -d= -f2-)" \
  -e WORDPRESS_DB_NAME="$(grep '^DB_NAME=' .env | cut -d= -f2-)" \
  --user 33:33 wordpress:cli \
  wp search-replace 'https://produzione.example' 'http://localhost:8080' \
  --all-tables-with-prefix --skip-columns=guid

Fai prima un backup e prova inizialmente con --dry-run. Non modificare i GUID: non sono URL di navigazione e normalmente devono restare stabili.

Backup e ripristino

I comandi seguenti chiedono la password invece di inserirla nella cronologia della shell:

# backup
docker compose exec db sh -c \
  'mariadb-dump -uroot -p --single-transaction --routines --triggers "$MARIADB_DATABASE" > /backup/wordpress.sql'

# ripristino nel database esistente
docker compose exec db sh -c \
  'mariadb -uroot -p "$MARIADB_DATABASE" < /backup/wordpress.sql'

Per ricreare il database da un dump iniziale:

docker compose down
# Attenzione: elimina definitivamente i dati del database locale.
docker volume rm "$(docker volume ls -q --filter label=com.docker.compose.project=docker-wordpress --filter label=com.docker.compose.volume=db_data)"
cp /percorso/dump.sql db/init/
docker compose up -d

Se hai cambiato COMPOSE_PROJECT_NAME, sostituisci docker-wordpress nel filtro.

Comandi utili

docker compose logs -f wordpress db
docker compose exec wordpress bash
docker compose exec db mariadb -uwordpress -p wordpress
docker compose pull
docker compose up -d
docker compose down                 # mantiene i volumi
docker compose down --volumes       # elimina tutti i dati locali dello stack

docker compose pull seguito da up -d aggiorna i tag mobili. Per upgrade del database tra major version consulta prima le note di MariaDB e conserva un dump.

Note di sicurezza

Questa configurazione usa password di sviluppo nel file .env, abilita il debug WordPress e non configura TLS, hardening o backup automatici. .env è ignorato da Git, ma non inserire comunque credenziali reali. Non esporre lo stack su Internet e non usarlo per il deploy di produzione.

Riferimenti

• Immagine ufficiale WordPress
• Immagine ufficiale MariaDB
• Mailpit
• Docker Compose
• WP-CLI search-replace

Licenza

MIT