Sync DB + Uploads

Plugin WP-CLI per sincronizzare database e cartella uploads tra ambiente locale e server remoto Hetzner per qualsiasi sito che segue il tuo scaffolding Docker canonico.

Il plugin non espone interfacce nel backoffice WordPress: i comandi sono disponibili solo da WP-CLI.

Obiettivo

Il plugin fornisce tre comandi:

• status: valida ambiente e configurazione risolta
• push: sovrascrive il target remoto con database e/o uploads locali
• pull: sovrascrive il target locale con database e/o uploads remoti

Durante la sync:

• viene creato un backup prima delle operazioni distruttive
• il database viene trasferito tramite dump SQL
• gli uploads vengono sincronizzati con rsync --delete
• al termine della sync DB viene eseguito il rewrite delle URL
• viene eseguito cache flush

Convenzioni richieste dallo scaffolding

Il plugin assume questo layout come canonico.

Locale:

• progetto con ./wp montato in /var/www/html
• progetto con ./db montato in /db
• esecuzione dei comandi nel servizio/container wpcli
• hostname locale risolto da WordPress tramite home_url()

Remoto Hetzner:

• root siti in /opt/wp-sites
• sito remoto in /opt/wp-sites/<slug>
• file compose remoto docker-compose.yml
• servizio remoto wpcli
• WordPress remoto montato in /var/www/html

Lo slug viene derivato da DB_NAME. Nel tuo scaffolding corrente coincide con il nome del sito.

Configurazione automatica canonica

Se i tuoi siti seguono sempre questa convenzione:

• URL pubblico https://test.michelepaolino.com/<slug>
• endpoint SSH root@188.245.205.247

non devi configurare nulla per sito.

Il plugin deriva:

• slug da DB_NAME
• REMOTE_URL come https://test.michelepaolino.com/<slug>
• REMOTE_SSH come root@188.245.205.247

Override per sito

Se un sito esce dalla convenzione canonica, puoi dichiarare override in wp-config.php o tramite WORDPRESS_CONFIG_EXTRA:

define('SYNC_DB_UPLOADS_REMOTE_SSH', 'root@example-host');
define('SYNC_DB_UPLOADS_REMOTE_URL', 'https://example.com/path');

Configurazione opzionale

Se devi uscire ulteriormente dalle convenzioni canoniche, puoi aggiungere override:

define('SYNC_DB_UPLOADS_REMOTE_BASE_DIR', '/opt/wp-sites');
define('SYNC_DB_UPLOADS_REMOTE_COMPOSE_FILE', 'docker-compose.yml');
define('SYNC_DB_UPLOADS_REMOTE_WPCLI_SERVICE', 'wpcli');
define('SYNC_DB_UPLOADS_REMOTE_WP_PATH', '/var/www/html');
define('SYNC_DB_UPLOADS_LOCAL_DB_DIR', '/db/sync-db-uploads');
define('SYNC_DB_UPLOADS_LOCAL_BACKUP_DIR', WP_CONTENT_DIR . '/sync-db-uploads-backups');
define('SYNC_DB_UPLOADS_SSH_OPTIONS', '-o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null');

Come il plugin risolve i path

Valori derivati automaticamente:

• local_url: da home_url('/')
• local_uploads: da wp_get_upload_dir()['basedir']
• slug: da DB_NAME
• remote_site_dir: <REMOTE_BASE_DIR>/<slug>
• remote_db_dir: <remote_site_dir>/db/sync-db-uploads
• remote_backup_dir: <remote_site_dir>/wp/wp-content/sync-db-uploads-backups
• remote_uploads: <remote_site_dir>/wp/wp-content/uploads
• remote_compose_path: <remote_site_dir>/<REMOTE_COMPOSE_FILE> se non assoluto
• remote_compose_project: <slug>

Prerequisiti

Il comando richiede:

• esecuzione da ambiente WP-CLI
• binari disponibili: ssh, rsync, tar, gzip
• directory /root/.ssh disponibile nel container wpcli
• accesso SSH non interattivo al server remoto
• docker compose disponibile sul server remoto
• servizio remoto wpcli funzionante nel compose del sito

Se /root/.ssh non è montata nel container, il plugin interrompe l'esecuzione con errore.

Utilizzo

Verifica configurazione e dipendenze:

wp sync-db-uploads status

Sync completa verso il remoto:

wp sync-db-uploads push

Sync completa dal remoto al locale:

wp sync-db-uploads pull

Sync parziale:

wp sync-db-uploads push --only=db
wp sync-db-uploads push --only=uploads
wp sync-db-uploads pull --only=db
wp sync-db-uploads pull --only=uploads

Salto conferma interattiva:

wp sync-db-uploads push --yes
wp sync-db-uploads pull --only=db --yes

Esecuzione tramite Docker

Pattern operativo tipico:

docker compose run --rm wpcli wp sync-db-uploads status
docker compose run --rm wpcli wp sync-db-uploads push --only=db
docker compose run --rm wpcli wp sync-db-uploads pull --yes

Backup generati

Prima di ogni operazione distruttiva il plugin crea backup timestampati.

Backup locali:

• database prima di pull: <LOCAL_BACKUP_DIR>/db-before-pull-YYYYmmdd-HHMMSS.sql
• uploads prima di pull: <LOCAL_BACKUP_DIR>/uploads-before-pull-YYYYmmdd-HHMMSS.tar.gz

Backup remoti:

• database prima di push: <REMOTE_BACKUP_DIR>/db-before-push-YYYYmmdd-HHMMSS.sql
• uploads prima di push: <REMOTE_BACKUP_DIR>/uploads-before-push-YYYYmmdd-HHMMSS.tar.gz

Dump temporanei di lavoro:

• locale: <LOCAL_DB_DIR>
• remoto: <REMOTE_SITE_DIR>/db/sync-db-uploads

Effetti collaterali importanti

• rsync --delete rimuove dal target i file non presenti nella sorgente
• push sovrascrive database e uploads remoti
• pull sovrascrive database e uploads locali
• il rewrite URL non modifica la colonna guid
• il plugin assume che il compose remoto monti ./db dentro il container wpcli come /db

Migrazione dal plugin hardcoded

La versione attuale non contiene fallback legacy per siti specifici.

Per migrare:

1. aggiorna il plugin
2. definisci almeno SYNC_DB_UPLOADS_REMOTE_SSH e SYNC_DB_UPLOADS_REMOTE_URL
3. esegui wp sync-db-uploads status
4. se il tuo deploy remoto non segue il layout canonico, aggiungi gli override opzionali

Troubleshooting

SYNC_DB_UPLOADS_REMOTE_SSH non valido

• usa il formato user@host

SYNC_DB_UPLOADS_REMOTE_URL non valido

• usa una URL assoluta completa di schema

Errore su dipendenze mancanti:

• verifica che ssh, rsync, tar e gzip siano installati nel container wpcli

Errore relativo a /root/.ssh:

• ricostruisci o aggiorna il servizio wpcli montando la chiave SSH necessaria

Connessione SSH fallita:

• verifica raggiungibilità del server, chiave autorizzata e permessi dell'utente remoto

Comandi WP remoti falliti:

• verifica la presenza del compose remoto nel path risolto da status
• verifica che il progetto compose remoto esponga il servizio wpcli
• verifica che ./db sia montato nel container remoto come /db