Deploy

Il workflow del sito

.github/workflows/deploy.yml parte su:

push su main;
workflow_dispatch manuale;
repository_dispatch con event_type: wp-content-update (dal webhook WordPress).

Fa: checkout → Node 24 → npm ci → npm run quality → sync di dist/ via FTPS.

Secrets

Secret	Uso
`WORDPRESS_API_BASE_URL`	URL REST del WordPress di produzione
`SITE_URL`	URL pubblico del sito (canonical, sitemap)
`FTP_SERVER`	host FTP/FTPS
`FTP_USERNAME`	utente
`FTP_PASSWORD`	password
`FTP_REMOTE_DIR`	cartella remota (es. `/httpdocs/`)

Finché WORDPRESS_API_BASE_URL manca, tutti gli step vengono saltati e il job resta verde: il primo push di un template non produce un deploy rosso. Appena aggiungi i secrets, il deploy riparte al push successivo.

Cosa fa il quality gate

npm run quality = typecheck → lint → test → build. Se un contratto dati è rotto, la build fallisce e il sync FTPS non parte. Il sito vecchio resta online: è un comportamento voluto, meglio di pubblicare dati sbagliati.

Il workflow della guida

.github/workflows/guide.yml builda guide/ e pubblica il risultato sul branch gh-pages. GitHub Pages può servire quel branch (se il repository lo consente).

Hosting: FTPS vs alternative

Il template è statico: qualsiasi hosting che serva file va bene.

Hosting	Note
FTP/FTPS tradizionale	il workflow incluso; `.htaccess` per HTTPS, 404, cache, gzip
Netlify	collega il repo, build command `npm run build`, publish `dist`
Cloudflare Pages	build `npm run build`, output `dist`, Node 24
GitHub Pages	solo per la guida in questo repository; per il sito servono repo pubblico o piano pagato
S3 + CloudFront	più configurazione, ottimo per volumi alti

Se cambi hosting, disattiva il workflow FTPS o rendilo manuale.

HTTPS, 404 e cache

public/.htaccess (copiato in dist/):

redirect HTTP → HTTPS;
ErrorDocument 404 /404.html (la pagina generata da 404.astro);
cache lunga per /_astro/ (asset con hash);
gzip per HTML/CSS/JS/JSON/SVG.

Su Netlify/Cloudflare questa parte è gestita dalla piattaforma.

Sitemap e robots

@astrojs/sitemap genera sitemap-index.xml usando SITE_URL.
public/robots.txt punta alla sitemap: aggiorna il dominio.
La 404 è esclusa dalla sitemap dal filtro in astro.config.mjs.

Rollback

Lo statico aiuta: ogni commit è una versione completa.

Rollback veloce: git revert del commit incriminato e push → il workflow ricostruisce e risincronizza.
Rollback d’emergenza: ri-esegui un run precedente da GitHub Actions (se i file sono ancora disponibili) o ripristina un backup della cartella remota.
Il database WordPress non viene toccato dal deploy: un rollback del frontend non perde contenuti.

Verifica dopo il deploy

Home, /eventi, un dettaglio evento, /contatti.
Form contatti: invio reale e ricezione email.
Immagini: nessuna 404.
robots.txt e sitemap-index.xml rispondono.
Cache: un hard refresh mostra la nuova versione.

Deploy della guida

La guida è un sito statico separato (Astro Starlight) pubblicato su https://headless.jevis.it/, servito da nginx su VPS.

Il workflow .github/workflows/guide.yml builda guide/ e sincronizza guide/dist/ via rsync su SSH. Secrets:

Secret	Valore
`GUIDE_SSH_HOST`	IP o hostname del VPS
`GUIDE_SSH_USER`	utente SSH che può scrivere nella document root
`GUIDE_SSH_KEY`	chiave privata SSH (intera, con BEGIN/END)
`GUIDE_REMOTE_DIR`	cartella remota, es. `/var/www/headless.jevis.it`

Senza GUIDE_SSH_HOST gli step sono saltati e il job resta verde.

La configurazione nginx di riferimento è in deploy/nginx/headless.jevis.it.conf: server block su porta 80, try_files per le URL pulite, cache per /_astro/, 404 custom, gzip. Il certificato si emette con certbot --nginx -d headless.jevis.it.

Checklist pre-go-live

SITE_URL corretto e public/robots.txt aggiornato
public/og-image presente e meta social verificati
Form contatti: email destinatario e prova reale
Privacy/Cookie/Termini caricati e URL inseriti in WordPress
XML-RPC disattivato
Webhook: PAT con Contents: Read and write e costanti in wp-config.php
Backup WordPress e database
Monitoraggio uptime e Search Console