Files
Studio_Grasso/docs/DEPLOY.md
T
Claude 0a718a8f6d fix: correzioni della verifica indipendente
- privacy (modalità php): conservazione dell'impronta HMAC descritta come
  avviene davvero; cron facoltativo in DEPLOY.md
- contitolarità con Google: punto di contatto e verifica dell'accordo
  ex art. 26 in TODO B4; informativa breve con art. 6.1.b o f
- «titolo conseguito in Italia» tolto: dato da confermare (statoTitolo,
  TODO C13); qualifica CAF del Dott. Ezio Grasso con la dicitura ufficiale
- mappe: il consenso carica tutte le mappe della pagina
- Esc sul sottomenu riporta il focus sul pulsante; sidebar «Altri servizi»
- resa: anello CTA ancorato al contenuto, colonna legale allineata alla
  testa, spazi non separabili anche nei testi legali e nel ruolo, «tel.»
  unito al numero, a capo dopo la @ nel pulsante e-mail, breadcrumb
- contact.php: UTF-8 non valido rifiutato, nessun avviso con open_basedir,
  apostrofi tipografici; CSP con direttive ripetute segnalate;
  --shell-safe neutralizza ogni $
- DEPLOY: ordine dei passi della modalità endpoint; TODO B2/C13 e righe
- date di aggiornamento dei testi legali

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016zJ9ZWGKvoKoxYwbmnRKdJ
2026-10-16 00:49:49 +00:00

11 KiB

Pubblicare il sito sull'hosting

Il sito è un insieme di file statici: funziona su qualsiasi hosting (Apache/LiteSpeed con o senza PHP, nginx, object storage). Ogni release pubblicata su Forgejo contiene:

File Uso
sito-studio-grasso-vX.Y.Z.zip formato consigliato per i pannelli di hosting (cPanel, Plesk, Aruba, Register, SiteGround…)
sito-studio-grasso-vX.Y.Z.tar.gz server Linux con accesso SSH, nginx, object storage
SHA256SUMS.txt impronte per verificare che i file scaricati siano integri
BUILD-INFO.txt versione, commit, data e strumenti usati per la build

Il contenuto del sito è alla radice dell'archivio (non c'è una cartella da aprire): index.html, 404.html, .htaccess, robots.txt, sitemap-index.xml, le cartelle delle pagine e _astro/.

Il file .htaccess è nascosto (inizia con un punto): assicurarsi che il programma FTP o il file manager mostri i file nascosti e che venga caricato.

1. Scaricare e verificare il pacchetto

Dalla pagina Release del repository Forgejo scaricare lo zip (o il tar.gz) e SHA256SUMS.txt nella stessa cartella, poi:

sha256sum -c SHA256SUMS.txt --ignore-missing     # Linux
shasum -a 256 -c SHA256SUMS.txt --ignore-missing # macOS

Su Windows (PowerShell): Get-FileHash .\sito-studio-grasso-vX.Y.Z.zip -Algorithm SHA256 e confrontare con la riga corrispondente di SHA256SUMS.txt.

2. Hosting con pannello (cPanel, Plesk, DirectAdmin…)

  1. Aprire il File Manager del pannello ed entrare nella cartella pubblica del dominio (public_html su cPanel, httpdocs su Plesk).
  2. Fare una copia di sicurezza del sito esistente (o scaricarla), poi svuotare la cartella.
  3. Caricare lo zip e usare Estrai (Extract) nella stessa cartella.
  4. Verificare che nella cartella ci siano index.html e .htaccess (attivare «mostra file nascosti»), poi eliminare lo zip.
  5. Attivare il certificato HTTPS (Let's Encrypt/AutoSSL) dal pannello, se non è già attivo.

Note sul .htaccess

  • Il redirect HTTP → HTTPS è attivo: se l'hosting lo gestisce già dal pannello, o se il certificato non è ancora attivo, commentare le tre righe indicate nella sezione «Redirect».
  • Il redirect tra dominio con e senza «www» è commentato: decommentare la variante coerente con il dominio usato per la build (SITE_URL, predefinito https://www.grassoezio.it → variante A).
  • HSTS è commentato: attivarlo solo quando HTTPS funziona su tutto il dominio.
  • Se compare un errore 500 dopo il caricamento, l'hosting non consente una direttiva: commentare la riga indicata nel log degli errori del pannello (tutte le direttive dei moduli sono già dentro <IfModule>).
  • La configurazione è stata provata su Apache 2.4 con AllowOverride All (vedi DECISIONS.md, D-034).

3. FTP / SFTP

  1. Estrarre lo zip sul proprio computer in una cartella vuota.
  2. Con il programma FTP (es. FileZilla, modalità di trasferimento automatica o binaria) caricare il contenuto della cartella, .htaccess compreso, nella cartella pubblica del dominio, sostituendo i file esistenti.
  3. Eliminare dal server i file del vecchio sito non più presenti (es. vecchie pagine .php o .html), dopo averne fatto una copia.

4. Server con nginx

  1. Copiare sito-studio-grasso-vX.Y.Z.tar.gz sul server ed estrarlo:

    sudo mkdir -p /var/www/studio-grasso
    sudo tar -xzf sito-studio-grasso-vX.Y.Z.tar.gz -C /var/www/studio-grasso
    
  2. Usare come base deploy/nginx.conf.example (redirect HTTPS e www, try_files, error_page 404, header di sicurezza, cache, compressione, blocco dei file nascosti): adattare server_name e certificati, poi sudo nginx -t && sudo systemctl reload nginx.

  3. Il .htaccess è ignorato da nginx (e bloccato dalla configurazione).

5. Object storage (S3 compatibile, hosting statico)

  1. Estrarre il tar.gz e caricare il contenuto nel bucket (es. rclone sync sito/ remote:bucket), con «documento indice» index.html e «documento di errore» 404.html.
  2. Il .htaccess non è usato: configurare nel CDN o nel servizio redirect HTTPS, il redirect /privacy → /privacy-policy/ e gli header di sicurezza (Content-Security-Policy, X-Content-Type-Options, Referrer-Policy, X-Frame-Options, Permissions-Policy) come in public/.htaccess.

6. Modulo di contatto (facoltativo)

Per impostazione predefinita il modulo è disattivato (contactForm.mode = 'off'): la pagina Contatti mostra il pulsante «Scrivi a info@studiograssoezio.it». Nessun dato passa dal server del sito.

Modalità php (hosting con PHP 7.4+ e funzione mail(); l'estensione mbstring non è necessaria)

  1. In src/data/studio.ts impostare mode: 'php' (oggetto contactForm).
  2. Copiare deploy/optional-php-form/contact.php in public/contact.php e controllare le costanti in testa al file: DESTINATARIO (predefinito info@studiograssoezio.it) e MITTENTE. MITTENTE deve essere una casella esistente di un dominio da cui l'hosting può spedire, coperto da SPF/DKIM (es. noreply@ sul dominio del sito o della posta). È usata anche come mittente della busta (-f): con un mittente non autorizzato le richieste possono finire nello spam o essere respinte, anche se il sito mostra «Richiesta inviata».
  3. npm run verify, commit e nuova release: il pacchetto conterrà contact.php.
  4. Dopo il deploy inviare una richiesta di prova e verificare la ricezione (anche nella cartella spam).

Il gestore:

  • valida i campi e scarta in silenzio gli invii con il campo trappola compilato;
  • rifiuta gli invii troppo rapidi (meno di 3 secondi) e quelli oltre 5 all'ora dallo stesso indirizzo IP;
  • non salva il contenuto dei messaggi e reindirizza a /contatti/grazie/.

Il contatore degli invii è un file per IP con un nome crittografico (HMAC dell'IP con un segreto casuale generato al primo uso). I contatori più vecchi di un'ora vengono cancellati al primo invio successivo; per cancellarli comunque entro l'ora si può aggiungere un'operazione pianificata (cron) dell'hosting, es. find ~/.studio-grasso-form -name 'ip-*' -mmin +60 -delete. Sta in una cartella privata fuori dalla cartella pubblica: la costante CARTELLA_LIMITI, predefinita ../.studio-grasso-form, cioè accanto a public_html. Se l'hosting non permette di scrivere lì, indicare una cartella privata scrivibile. Senza una cartella sicura il limite non si applica.

La Privacy policy si aggiorna automaticamente.

Modalità endpoint (servizio esterno di gestione moduli)

  1. Scegliere un fornitore con sede e server nell'Unione europea e conforme al GDPR; nominarlo responsabile del trattamento.
  2. In src/data/studio.ts impostare mode: 'endpoint', endpoint: 'https://…' e, in studio.fornitori.modulo, denominazione e sede del fornitore (senza, la build si ferma): compaiono nella Privacy policy e sotto il modulo.
  3. Aggiornare la Content-Security-Policy (public/.htaccess e deploy/nginx.conf.example): aggiungere l'origine del fornitore a form-action, nella stessa direttiva (es. form-action 'self' https://moduli.esempio.eu). npm run test:compliance verifica che l'origine di contactForm.endpoint sia presente e che nessuna direttiva sia ripetuta.
  4. Verificare il modulo: npm run build && npx playwright test tests/e2e/form.spec.ts (l'invio al fornitore è simulato, nessuna richiesta esterna), poi npm run verify.
  5. Far rivedere la Privacy policy al consulente.

7. Controlli dopo la pubblicazione

  • https:// attivo, il lucchetto del browser è presente e http:// reindirizza a https://.
  • Il dominio con/senza «www» reindirizza alla versione usata in SITE_URL.
  • https://dominio/privacy reindirizza a /privacy-policy/; https://dominio/studio a /studio/.
  • Un indirizzo inesistente (es. /prova-404/) mostra la pagina «Pagina non trovata».
  • https://dominio/sitemap-index.xml e /robots.txt sono raggiungibili.
  • Gli header di sicurezza sono presenti (es. con securityheaders.com o curl -I https://dominio/).
  • Le mappe si caricano solo premendo «Carica la mappa».
  • Lighthouse sul sito pubblicato (Chrome → DevTools → Lighthouse, modalità mobile): valori in linea con quelli della CI.
  • Modulo (se attivo): richiesta di prova ricevuta.
  • Google Search Console: inviare la sitemap sitemap-index.xml (facoltativo).

8. Tornare alla versione precedente

Scaricare dalla pagina Release il pacchetto della versione precedente e ripetere la procedura (sezioni 2, 3, 4 o 5). Ogni release è completa e indipendente.

9. Deploy automatico (facoltativo, da attivare quando l'hosting è definito)

deploy/forgejo-deploy.yml.example è un workflow pronto ma non attivo: alla pubblicazione di una release (o su avvio manuale) scarica il pacchetto, ne verifica l'impronta e lo pubblica, poi controlla che le pagine principali rispondano.

  1. Copiarlo in .forgejo/workflows/deploy.yml.
  2. Decommentare una variante e creare i segreti del repository (Impostazioni → Actions → Segreti):
    • A — rsync su SSH: DEPLOY_HOST, DEPLOY_USER, DEPLOY_PATH, DEPLOY_SSH_KEY (chiave privata dedicata, con la chiave pubblica in ~/.ssh/authorized_keys sul server);
    • B — FTPS con lftp: FTP_HOST, FTP_USER, FTP_PASSWORD, FTP_PATH (es. /public_html);
    • C — rclone (object storage): RCLONE_CONFIG (contenuto di rclone.conf), RCLONE_DEST.
  3. Avvio automatico: gli eventi creati con il token automatico dei workflow non avviano altri workflow. Perché il deploy parta da solo alla pubblicazione di una release, release.yml deve usare un token personale: segreto FORGEJO_TOKEN (o RELEASE_TOKEN, vedi README, «Fare una release»). Senza il segreto il deploy si avvia a mano dalla scheda Actions (indicando il tag).
  4. Facoltativo: variabile del repository SITE_URL per il controllo finale.
  5. Le varianti A e B sincronizzano la cartella con --delete ma non toccano .well-known/, .user.ini e cgi-bin/, gestiti dall'hosting. Se l'hosting ne usa altri, aggiungere le esclusioni.
  6. Aggiungere al passo «Strumenti» i programmi della variante scelta (rsync openssh-client, lftp o rclone).

10. Pubblicare la release a mano (senza workflow)

Se le Actions non sono disponibili:

RELEASE_VERSION=vX.Y.Z npm run package
FORGEJO_URL=https://forgejo.example.it FORGEJO_REPO=proprietario/repository \
FORGEJO_TOKEN=<token write:repository> scripts/release-upload.sh vX.Y.Z

Il tag deve già esistere sul server (git push origin vX.Y.Z). Lo script crea la release (o aggiorna quella esistente) con le note del CHANGELOG e carica i quattro file di release/.