Le run della CI restavano «in attesa» perché l'unico runner dell'istanza («Ferrari») non si è mai collegato: il runner resta da configurare. La revisione completa del codice ha trovato anche difetti che avrebbero fatto fallire la CI con il runner online, oltre ad altri problemi del sito, dei controlli e della documentazione. CI e rilascio: - continue-on-error sullo step dei link esterni: Forgejo lo ignora sul job, e un sito esterno irraggiungibile avrebbe reso rossa la CI; - artifact con i file nascosti (report Lighthouse e .htaccess non venivano mai caricati); - token personale RELEASE_TOKEN: FORGEJO_TOKEN è riservato ed è sempre il token automatico; - dominio in un solo punto (site.config.mjs) e variabile del repository SITE_URL; - ripiego REST: release in bozza, file, poi pubblicazione; tag verificato sul server; sostituzione dei file senza mai lasciarli mancanti; - tar.gz identico su Windows, macOS e Linux (byte del sistema operativo nell'header gzip). Sito: CSS compatibile con Safari/iOS 15 (media query classiche, backdrop-filter), anello di focus con contrasto di almeno 3:1, bersagli touch di 44 px dove servono, intestazione desktop senza voci o logo a capo, HTML valido in /servizi/, colore delle chip, stampa senza mappe, giorni di apertura, ricerca e titolo delle mappe e numero breve ricavati dai dati. Modulo di contatto e contact.php: stesse regole nel browser e sul server (spazi, e-mail, a capo, lunghezze), tempo minimo misurato con un solo orologio (ts_invio), corpo in quoted-printable e oggetto RFC 2047, funzionamento con PHP a 32 bit, costante MODALITA_PREDEFINITA per attivarlo. Controlli e test: valori letti dai dati del sito, i sei servizi del brief con le ancore, «commercialista» anche in meta, attributi e dati strutturati, .htaccess su righe attive, HSTS attivabile con una scelta esplicita, contrasto del focus misurato nei test. Esempi di pubblicazione: nginx con gli header di sicurezza in un solo punto (HSTS compreso), deploy automatico che parte alla pubblicazione e sincronizza solo una cartella confermata, procedura nginx che toglie i file delle versioni precedenti. Debug: .vscode/launch.json e tasks.json, F5 avvia il server Astro e apre il browser con il debugger collegato. Documentazione aggiornata (README, DEPLOY, CONTENUTI, CONFORMITA, TODO-STUDIO, CHANGELOG) e decisioni D-045…D-055. Verificato: npm run verify su Windows e nel container della CI (Playwright 1.56.1, root); job dei link esterni in node:24; contact.php con PHP 7.4 e 8.3, a 64 e 32 bit; nginx in Docker; release-upload.sh e deploy di esempio contro API e shell simulate. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 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…)
- Aprire il File Manager del pannello ed entrare nella cartella pubblica del dominio (
public_htmlsu cPanel,httpdocssu Plesk). - Fare una copia di sicurezza del sito esistente (o scaricarla), poi svuotare la cartella.
- Caricare lo zip e usare Estrai (Extract) nella stessa cartella.
- Verificare che nella cartella ci siano
index.htmle.htaccess(attivare «mostra file nascosti»), poi eliminare lo zip. - 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.config.mjso variabileSITE_URL, predefinitohttps://www.grassoezio.it→ variante A). - HSTS è commentato: attivarlo solo quando HTTPS funziona su tutto il dominio, decommentando la riga in
public/.htaccesse impostandoHSTS_ATTIVO = trueinscripts/check-compliance.mjs(così la verifica controlla che sia attivo invece di segnalarlo come errore), poi nuova release. - 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
- Estrarre lo zip sul proprio computer in una cartella vuota.
- Con il programma FTP (es. FileZilla, modalità di trasferimento automatica o binaria) caricare il contenuto della cartella,
.htaccesscompreso, nella cartella pubblica del dominio, sostituendo i file esistenti. - Eliminare dal server i file del vecchio sito non più presenti (es. vecchie pagine
.phpo.html), dopo averne fatto una copia.
4. Server con nginx
-
Copiare
sito-studio-grasso-vX.Y.Z.tar.gzsul server, estrarlo in una cartella temporanea e sincronizzare la cartella servita. Così vengono tolti anche i file che non fanno più parte del sito: estraendo direttamente nella cartella servita, le pagine eliminate in una nuova versione (o aggiunte in una versione più recente, quando si torna indietro) resterebbero raggiungibili.sudo mkdir -p /var/www/studio-grasso d=$(sudo mktemp -d) sudo tar -xzf sito-studio-grasso-vX.Y.Z.tar.gz -C "$d" sudo rsync -rlt --delete --exclude .well-known/ "$d"/ /var/www/studio-grasso/ sudo rm -rf "$d"rsync -rlt(non-a) lascia invariati permessi e proprietario della cartella servita. Senza rsync: svuotare la cartella (tranne.well-known/) e poi estrarre l'archivio. La stessa procedura vale per gli aggiornamenti e per tornare a una versione precedente. -
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): adattareserver_namee certificati, poisudo nginx -te, se l'esito è positivo,sudo systemctl reload nginx. Gli header di sicurezza stanno solo nel bloccoservere valgono per ogni risposta: non aggiungereadd_headerdentro lelocation, perché annullerebbe tutti quelli ereditati (HSTS compreso). -
Il
.htaccessè ignorato da nginx (e bloccato dalla configurazione).
5. Object storage (S3 compatibile, hosting statico)
- Estrarre il tar.gz e caricare il contenuto nel bucket (es.
rclone sync sito/ remote:bucket), con «documento indice»index.htmle «documento di errore»404.html. - Il
.htaccessnon è 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 inpublic/.htaccess.
6. Modulo di contatto (facoltativo)
Per impostazione predefinita il modulo è disattivato (MODALITA_PREDEFINITA = 'off' in src/data/studio.ts): 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)
- In
src/data/studio.tsimpostareMODALITA_PREDEFINITA = 'php'. Cambiare solo quella costante: la lettura della variabileCONTACT_FORM_MODE(usata nei test) deve restare. - Copiare
deploy/optional-php-form/contact.phpinpublic/contact.phpe controllare le costanti in testa al file:DESTINATARIO(predefinitoinfo@studiograssoezio.it) eMITTENTE.MITTENTEdeve 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». npm run verify(segnala secontact.phpmanca inpublic/), commit e nuova release: il pacchetto conterràcontact.php.- Dopo il deploy inviare una richiesta di prova e verificare la ricezione (anche nella cartella spam).
Il gestore:
- valida i campi con le stesse regole del browser (spazi iniziali e finali esclusi, a capo contati come un carattere, e-mail con dominio completo) e scarta in silenzio gli invii con il campo trappola compilato;
- rifiuta gli invii troppo rapidi (meno di 3 secondi, misurati con l'orologio del dispositivo) e quelli oltre 5 all'ora dallo stesso indirizzo IP;
- invia l'e-mail in quoted-printable (righe brevi: un messaggio lungo scritto senza andare a capo non viene respinto dal server di posta);
- 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)
- Scegliere un fornitore con sede e server nell'Unione europea e conforme al GDPR; nominarlo responsabile del trattamento.
- In
src/data/studio.tsimpostareMODALITA_PREDEFINITA = 'endpoint',endpoint: 'https://…'(oggettocontactForm) e, instudio.fornitori.modulo, denominazione e sede del fornitore (senza, la build si ferma): compaiono nella Privacy policy e sotto il modulo. - Aggiornare la Content-Security-Policy (
public/.htaccesse, per nginx, l'unica rigaContent-Security-Policydel bloccoserverindeploy/nginx.conf.example): aggiungere l'origine del fornitore aform-action, nella stessa direttiva (es.form-action 'self' https://moduli.esempio.eu).npm run test:complianceverifica che l'origine dicontactForm.endpointsia presente e che nessuna direttiva sia ripetuta. - Verificare il modulo:
npm run build, poinpx playwright test tests/e2e/form.spec.ts(l'invio al fornitore è simulato, nessuna richiesta esterna), poinpm run verify. - Far rivedere la Privacy policy al consulente.
7. Controlli dopo la pubblicazione
https://attivo, il lucchetto del browser è presente ehttp://reindirizza ahttps://.- Il dominio con/senza «www» reindirizza alla versione usata per la build (
site.config.mjsoSITE_URL). https://dominio/privacyreindirizza a/privacy-policy/;https://dominio/studioa/studio/.- Un indirizzo inesistente (es.
/prova-404/) mostra la pagina «Pagina non trovata». https://dominio/sitemap-index.xmle/robots.txtsono 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. Togliere sempre i file della versione sostituita (cartella svuotata, punto 3 dell'FTP, sincronizzazione della sezione 4, rclone sync): altrimenti le pagine aggiunte nella versione più recente restano raggiungibili.
9. Deploy automatico (facoltativo, da attivare quando l'hosting è definito)
deploy/forgejo-deploy.yml.example è un workflow pronto ma non attivo: quando release.yml pubblica una release stabile (o su avvio manuale, indicando il tag) scarica il pacchetto, ne verifica l'impronta e lo pubblica, poi controlla che le pagine principali rispondano. Le pre-release (tag con «-», es. v1.1.0-rc.1) non vengono pubblicate, e nemmeno una release che non sia l'ultima. Modificare in seguito titolo o note di una release, anche dell'ultima, non avvia il deploy: parte solo la pubblicazione fatta dal workflow di release o da scripts/release-upload.sh. L'avvio manuale serve anche per tornare a una versione precedente: in quel caso segnare come pre-release la versione ritirata, così resta «ultima» quella online.
- Copiarlo in
.forgejo/workflows/deploy.yml. - 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_keyssul server).DEPLOY_PATHè la cartella pubblica del sito. Prima del primo deploy creare sul server il file di conferma.deploy-studio-grassoin quella cartella (es.touch /var/www/studio-grasso/.deploy-studio-grasso): senza, lo step si ferma, così un percorso sbagliato (la home,/var/www…) non viene mai sincronizzato con--delete. Lo step si ferma anche se il segreto manca o vale/,~,.,/homeo/root; - B — FTPS con lftp:
FTP_HOST,FTP_USER,FTP_PASSWORD,FTP_PATH(es./public_html).FTP_PATHè la cartella pubblica del sito, mai la radice dell'account quando questa è la home (cPanel): la sincronizzazione cancellerebbe posta, configurazioni e altri siti; - C — rclone (object storage):
RCLONE_CONFIG(contenuto dirclone.conf),RCLONE_DEST.
- A — rsync su SSH:
- Avvio automatico: le modifiche fatte con il token automatico dei workflow non avviano altri workflow. Perché il deploy parta da solo,
release.ymldeve pubblicare la release con un token personale: segretoRELEASE_TOKEN(vedi README, «Fare una release»). Non usare nomi che iniziano conFORGEJO_,GITEA_oGITHUB_: Forgejo li riserva, esecrets.FORGEJO_TOKENè sempre il token automatico. Senza il segreto il deploy si avvia a mano dalla scheda Actions (indicando il tag). - Facoltativo: variabile del repository
SITE_URL, usata dalla build di CI e release (dominio del sito). Il controllo finale del deploy usa la stessa variabile oppure, se non è impostata, il dominio scritto inBUILD-INFO.txtdel pacchetto (cioè quello disite.config.mjsal momento della build). - Le varianti A e B sincronizzano la cartella con
--deletema non toccano.well-known/,.user.iniecgi-bin/, gestiti dall'hosting. Se l'hosting ne usa altri, aggiungere le esclusioni. - Aggiungere al passo «Strumenti» i programmi della variante scelta (
rsync openssh-client,lftporclone).
10. Pubblicare la release a mano (senza workflow)
Se le Actions non sono disponibili (su Windows eseguire i comandi in Git Bash):
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 si ferma se manca o se punta a un commit diverso dal tag locale. Come l'action del workflow, crea la release in bozza, carica i quattro file di release/ e solo alla fine la pubblica con titolo e note del CHANGELOG. Se la release esiste già (anche come bozza lasciata da un tentativo non riuscito), sostituisce i file con lo stesso nome, caricando il nuovo prima di cancellare il vecchio, e la pubblica con le note aggiornate.