Il progetto vive in modo definitivo su Gitea: i workflow passano da .forgejo/ a .gitea/workflows/ e la documentazione non nomina più la piattaforma precedente. - ci.yml: i controlli di npm run verify sono passi separati (si vede subito quale è fallito) e alla fine la CI crea lo zip di rilascio e ne verifica il contenuto, così un errore di pacchetto emerge prima del tag. Runner ubuntu-latest, azioni da github.com con URL completo, upload-artifact@v3 (la v4 non funziona su Gitea). - release.yml: a ogni tag vX.Y.Z verifica tutto, crea lo zip e lo pubblica nella Release con scripts/release-upload.sh e l'API di Gitea, senza action esterne di release. - La release contiene un solo file, sito-studio-grasso-vX.Y.Z.zip (contenuto di dist/ alla radice, .htaccess compreso): tolti tar.gz, SHA256SUMS.txt e BUILD-INFO.txt da package.mjs, check-package.mjs e dalla documentazione. - release-upload.sh: variabili GITEA_*, si ferma su errori diversi da 404 invece di provare a creare la release, rifiuta una cartella vuota; provato su una finta API Gitea. - deploy/gitea-deploy.yml.example convertito per Gitea (resta disattivato). - Versione 1.0.1 pronta (package.json, CHANGELOG, D-056 e D-057 in DECISIONS.md); il tag v1.0.1 non è stato creato. Verifica: npm run verify completo (lint, formato, tipi, build, HTML, link, e2e 39, a11y 51, conformità 1455, Lighthouse) e npm run package eseguiti in una copia fuori da .claude/. I workflow non sono ancora stati eseguiti su un runner Gitea. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
17 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 Gitea (elenco delle release) contiene un solo file allegato, quello del sito:
| File | Uso |
|---|---|
sito-studio-grasso-vX.Y.Z.zip |
il sito pronto, per ogni tipo di hosting: pannelli (cPanel, Plesk, Aruba, Register, SiteGround…), FTP, server Linux con SSH, nginx, object storage |
Quale file scaricare. Nella pagina di ogni release Gitea aggiunge da solo anche «Source code (ZIP)» e «Source code (TAR.GZ)»: contengono il codice sorgente del sito, non il sito pronto, e non vanno caricati sull'hosting. Scaricare sempre e solo
sito-studio-grasso-vX.Y.Z.zip.
Il contenuto del sito è alla radice dello zip (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 controllare il pacchetto
-
Aprire l'elenco delle release del repository e, nella release che si vuole pubblicare (di norma la più recente), scaricare
sito-studio-grasso-vX.Y.Z.zip. Non scaricare i due «Source code». -
Facoltativo, ma utile prima di caricare il sito: estrarre lo zip in una cartella vuota del proprio computer e controllare che contenga
index.htmle.htaccess. Un file scaricato a metà o danneggiato dà un errore.Su Windows (PowerShell):
Expand-Archive .\sito-studio-grasso-vX.Y.Z.zip -DestinationPath .\sito Get-ChildItem .\sito -Force # devono comparire index.html e .htaccessSu Linux e macOS:
unzip -t sito-studio-grasso-vX.Y.Z.zip # «No errors detected» se lo zip è integro unzip -q sito-studio-grasso-vX.Y.Z.zip -d sito ls -a sito # devono comparire index.html e .htaccess
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
sito-studio-grasso-vX.Y.Z.zip(non i «Source code») 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 del sito sul proprio computer in una cartella vuota (sezione 1).
- 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.zipsul server (ad esempio conscp), estrarlo conunzipin 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 unzip -q sito-studio-grasso-vX.Y.Z.zip -d "$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 lo zip. Servono i programmiunzipersync(su Debian e Ubuntu:sudo apt install unzip rsync). 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 lo zip (
unzip -q sito-studio-grasso-vX.Y.Z.zip -d sito) 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 dall'elenco delle release lo zip sito-studio-grasso-vX.Y.Z.zip 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/gitea-deploy.yml.example è un workflow pronto ma non attivo: quando release.yml pubblica una release stabile (o su avvio manuale, indicando il tag) scarica lo zip sito-studio-grasso-vX.Y.Z.zip della release, ne controlla l'integrità (unzip -t) e la presenza di index.html e .htaccess, 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.
Per le release Gitea supporta gli eventi published (release non in bozza creata) ed edited (release modificata); una bozza non genera alcun evento. Il workflow di release crea la release in bozza, carica lo zip e solo allora la pubblica: Gitea notifica questo passaggio come modifica, non come published. Per questo il deploy ascolta entrambi gli eventi e il suo primo job («controllo») decide se procedere.
- Copiarlo in
.gitea/workflows/deploy.ymle committarlo sumain. Per gli eventi di release Gitea legge il workflow dal commit del tag: il file deve quindi essere già nel commit su cui è messo il tag. Per una release uscita prima di aggiungerlo, usare l'avvio manuale. - 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: Gitea non avvia workflow in risposta a ciò che fa il token automatico di un altro workflow (per evitare cicli). Perché il deploy parta da solo,
release.ymldeve quindi pubblicare la release con un token personale: segretoRELEASE_TOKEN, un access token con permessowrite:repository(vedi README, «Fare una release»). I nomi di segreti e variabili non possono iniziare conGITEA_oGITHUB_. Senza il segreto il deploy si avvia a mano dalla scheda Actions del repository (workflow «Deploy», indicando il tag). - Facoltativo: variabile del repository
SITE_URL(Impostazioni → Actions → Variabili), 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 della rigaSitemap:delrobots.txtcontenuto nello zip (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;unzipc'è già). - I job usano il label
ubuntu-latest, il predefinito diact_runner, comeci.ymlerelease.yml: sostituirlo se il runner ne usa un altro.
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
GITEA_URL=https://gitea.encke-hake.ts.net GITEA_REPO=BalboSoft/Studio_Grasso \
GITEA_TOKEN=<token write:repository> scripts/release-upload.sh vX.Y.Z
GITEA_TOKEN è un access token personale con permesso write:repository (Impostazioni utente → Applicazioni). Il tag deve già esistere sul server (git push origin vX.Y.Z): lo script (solo curl e node, usa l'API REST di Gitea) si ferma se manca o se punta a un commit diverso dal tag locale. Come il workflow, crea la release in bozza, carica lo zip 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 il file con lo stesso nome, caricando il nuovo prima di cancellare il vecchio, e la pubblica con le note aggiornate.