# Piano di implementazione 261113 — Ambiente sulla VPS OVH: Apache, rilasci e backup

| | |
|---|---|
| **Stato** | IN CORSO |
| **Creato il** | 13/11/2026 · **Rivisto il** 13/11/2026 (decisioni dell'utente: AlmaLinux, solo produzione, codice caricato a mano, nessuna copia remota; fase 3 ripianificata) |
| **Voci TODO coperte** | 0.8 "Predisporre staging e produzione sulla VPS OVH" (solo produzione, usata per ora come area di test) · 0.8 "Scrivere strumenti/backup.sh e strumenti/ripristino.sh ed eseguire la prima prova di ripristino" |
| **Esecuzione** | `/run-plan 261113` (tutte le fasi pronte) oppure `/run-plan 261113 <fase>` |

> Lanciare `/run-plan` vale come approvazione del piano.
> Le fasi 1–3 si eseguono **nel repository** (`/run-plan`). La fase 4 si esegue **sul server**, a mano, seguendo la guida prodotta nella fase 3: `/run-plan` non ha accesso SSH alla VPS.
> La fase 3 usa `strumenti/backup.sh` della fase 2: va eseguita **dopo** la fase 2.

---

## Stato delle fasi

| Fase | Contenuto | Dove | Stato | Stima |
|---|---|---|---|---|
| 1 | Modelli di configurazione Apache, PHP‑FPM, cron | repository | fatta (13/11/2026) — adattata ad AlmaLinux (decisione 1) | 3–4 h |
| 2 | `backup.sh` e `ripristino.sh` con test | repository | fatta (13/11/2026) — vedi "Esito" della fase | 5–7 h |
| 3 | Pacchetto di rilascio (PC), installazione e ritorno indietro (server), guida di installazione della VPS | repository | fatta (13/11/2026) — vedi "Esito" della fase | 8,5–12 h |
| 4 | Installazione della VPS, primo rilascio, cron di backup, prova di ripristino, collaudo Fase 1 | server (manuale) | pronta, dopo le fasi 1–3 | 5–7 h |
| 5 | HTTPS con Let's Encrypt e virtual host per nome | server | da pianificare (serve il DNS) | 1 h |
| | **Resta (fase 4)** | | | **5–7 h** |

**Come sono state stimate le ore:**
- La fase 2 contiene logica vera (cifratura, retention 7/4/12, checksum) e un test di andata e ritorno sul database di test. Il test deve girare sia in Git Bash su Windows sia su Linux, e le differenze tra `date` e `find` nei due ambienti richiedono qualche iterazione.
- La fase 3 è cresciuta rispetto alla prima versione del piano (2–3 h). Senza git sul server, il pacchetto va costruito sul PC (con le librerie Composer dentro) e installato sul server da uno script che deve: sostituire il codice senza perdere il `.env`, applicare le migrazioni prima dello scambio e saper tornare alla versione precedente. In più il test deve simulare un server finto (backup, migrazioni e `sudo` sostituiti da eseguibili di prova) e girare su Windows e Linux.
- La fase 4 dipende da incognite del server: versione di AlmaLinux (9 o 10) e quindi di PHP e MariaDB, SELinux, firewall OVH. Per questo la forchetta è ampia.

---

## Obiettivo

Mettere in piedi sulla VPS OVH l'ambiente **di produzione**, usato per ora come area di test, dove collaudare la Fase 1 e le successive. Deve:
- servire l'applicazione con **Apache + PHP‑FPM** in HTTPS;
- avere un **backup notturno** cifrato e una **prova di ripristino** documentata (requisito S3‑09, `documentazione/backup.md`);
- essere aggiornabile caricando a mano un pacchetto preparato sul PC, con un solo comando sul server e la possibilità di tornare indietro.

Contesto, al 13/11/2026:
- la VPS è acquistata, con AlmaLinux;
- il dominio sarà collegato da altri, quindi per ora si lavora **sull'indirizzo IP**;
- i testi privacy restano segnaposto;
- siamo in area test: niente dati reali.

### Punti emersi dall'analisi del codice

- Fuori da `sviluppo` l'applicazione marca il cookie di sessione come `Secure` e invia HSTS (`sorgenti/comune/sessione.php:36`, `sorgenti/comune/viste.php:145`). **In HTTP semplice il login non funziona**, quindi serve HTTPS anche prima del dominio. Soluzione: un certificato autofirmato sull'IP, con l'avviso del browser accettato a mano. I browser ignorano HSTS sugli indirizzi IP e sui certificati non validi, quindi non resta "bloccato" nulla. Alla fase 5 il certificato si sostituisce con Let's Encrypt.
- Gli header di sicurezza (CSP, X‑Frame‑Options e gli altri) sono già inviati da PHP. Apache aggiunge solo quelli per i file statici e nasconde la versione del server.
- `strumenti/migra.php` rifiuta le richieste web, ma la document root resta comunque solo `pubblico/`.
- L'IP del client per l'audit arriva da `REMOTE_ADDR` (`sorgenti/comune/audit.php:53`). Con Apache senza proxy davanti è corretto, quindi niente `mod_remoteip`.
- La migrazione 004 crea dei trigger: l'utente del database deve avere il privilegio `TRIGGER`. Se il log binario è attivo serve anche `log_bin_trust_function_creators=1` (già annotato in `ambienti.md`).
- Le migrazioni 001–004 usano `CHECK`, colonne `GENERATED ... STORED` e trigger: tutto supportato da MariaDB 10.5 (AlmaLinux 9) e 10.11 (AlmaLinux 10). In locale però si prova su 12.3, quindi la prima esecuzione sul server va controllata (fase 4).
- Senza casella SMTP si resta con `EMAIL_MODALITA=file`. Le email di conferma si leggono sul server in `dati/log/email/`.
- L'applicazione legge il `.env` da `app/.env` (`sorgenti/comune/avvio.php:107`): chi sostituisce la cartella `app/` deve portarsi dietro il `.env`.
- `strumenti/verifica_ambiente.sh` considera obbligatori `git` e `composer` dalla fase 1 (righe 244–253). Sul server non servono più (decisioni 6 e 7): senza modifiche la verifica fallirebbe.

---

## Decisioni (confermate dall'utente il 13/11/2026)

| # | Decisione | Scelta |
|---|---|---|
| 1 | Sistema operativo della VPS | **AlmaLinux**. Apache `httpd`, configurazione in `/etc/httpd/conf.d/`, pool in `/etc/php-fpm.d/`, SELinux attivo |
| 2 | Ambienti sulla VPS | **Solo produzione** (`DOMUSCAN_AMBIENTE=produzione`, cartella `/srv/domuscan/produzione/`), usata per ora come area di test. I modelli della fase 1 restano parametrici (`__AMBIENTE__`) |
| 3 | Certificato prima del dominio | **Autofirmato sull'IP**, valido 1 anno |
| 4 | Cifratura dei backup | **GPG a chiave pubblica**: sul server c'è solo la chiave pubblica; la privata, che serve al ripristino, resta offline al responsabile |
| 5 | Copia fuori dalla VPS | **Nessuna per il momento.** `BACKUP_REMOTO` resta vuoto: il backup è solo sulla VPS e lo script scrive un avviso a ogni esecuzione. Il supporto a `rclone` resta nello script, spento |
| 6 | Accesso del server al repository | **Nessuno.** Sul server non ci sono git né Composer |
| 7 | Rilascio | **Caricamento a mano** di un pacchetto preparato sul PC (fase 3) |

---

## Fase 1 — Modelli di configurazione del server (fatta il 13/11/2026)

File nuovi in `configurazione/server/`, versionati e senza segreti. Ogni file inizia con l'intestazione di progetto. Il nome dell'ambiente è un segnaposto `__AMBIENTE__`, sostituito in fase di installazione.

| File | Contenuto |
|---|---|
| `configurazione/server/apache_domuscan.conf` | Virtual host `:80` che fa solo redirect a HTTPS. Virtual host `:443` con `DocumentRoot /srv/domuscan/__AMBIENTE__/app/pubblico`, `SSLEngine on`, percorsi del certificato, `<Directory>` con `Options -Indexes -FollowSymLinks`, `AllowOverride None`, `Require all granted`. Blocco esplicito di file nascosti (`.env`, `.git`) e di `*.map`, `composer.*`. PHP tramite `proxy_fcgi` verso il socket del pool dedicato. `DirectoryIndex index.php`. Cache lunga per `risorse/`. Log separati per ambiente |
| `configurazione/server/apache_sicurezza.conf` | `ServerTokens Prod`, `ServerSignature Off`, `TraceEnable Off`. TLS solo 1.2/1.3 con cifrari moderni. `Header always set X-Content-Type-Options nosniff` per i file statici |
| `configurazione/server/php_fpm_domuscan.conf` | Pool `domuscan-__AMBIENTE__` con utente `domuscan-__AMBIENTE__` e socket dedicato, `pm = ondemand`. `php_admin_value`: `expose_php=Off`, `display_errors=Off`, `log_errors=On`, `error_log` nella cartella log dell'ambiente, `session.save_path` privato, `open_basedir` limitato a `app/`, `dati/` e `/tmp`, `upload_max_filesize` e `post_max_size` a 20M (pronti per la Fase 2) |
| `configurazione/server/cron_domuscan` | Riga del backup notturno alle 03:15 con l'utente di servizio e log dell'esito. Riga commentata per il futuro worker dei job (D9) |
| `configurazione/server/LEGGIMI.md` | Dove va copiato ogni file sul server e quali segnaposto sostituire |

**Moduli Apache:** `ssl` (pacchetto `mod_ssl`), `headers`, `proxy_fcgi`, `setenvif`, `rewrite`, già caricati dalla configurazione standard di AlmaLinux.

**Test automatico.** Nuovo `test/test_configurazione_server.sh`, stessa libreria e stesso stile dei test esistenti. Verifica che:
- i file esistano e abbiano l'intestazione;
- il `DocumentRoot` punti a `pubblico/`;
- ci siano `AllowOverride None`, `-Indexes` e il blocco dei file nascosti;
- `display_errors` sia `Off` nel pool;
- nessun file contenga password o chiavi.

Comando: `bash test/esegui_test.sh`.

**Fuori perimetro:** la sintassi Apache (`apachectl configtest`) si può controllare solo sul server, nella fase 4.

**Esito (13/11/2026):** modelli adattati ad AlmaLinux (percorsi `/etc/httpd`, `/etc/php-fpm.d`, `/run/php-fpm`, utente `apache`, regole SELinux in `LEGGIMI.md`). `test_configurazione_server.sh`: 32/32 superati.

---

## Fase 2 — Backup e ripristino (fatta il 13/11/2026, 5–7 h)

### `strumenti/backup.sh`

Legge il `.env` dell'ambiente (percorso passato con `--env`) e le variabili nuove (vedi sotto). Passi:
1. **Blocco** con `flock`, per evitare due esecuzioni sovrapposte.
2. `mariadb-dump --single-transaction --routines --triggers --events` del database, compresso con `gzip`, poi **cifrato con GPG** con la chiave pubblica `BACKUP_GPG_DESTINATARIO`. Il file in chiaro non viene mai scritto su disco: tutto passa in pipe.
3. **Archivio `tar` del Vault** (`PERCORSO_VAULT`; oggi vuoto, si riempirà dalla Fase 2 del pilota). I file del Vault sono già cifrati; l'archivio viene comunque cifrato con GPG, così i metadati (nomi e date) non restano in chiaro.
4. Archivio cifrato del **`.env`**, salvato in una sottocartella separata `configurazione/` dentro la cartella dei backup, come chiede `backup.md` ("conservata separatamente"). Le chiavi del sigillo e del Vault **non** sono incluse (restano offline).
5. File `SHA256SUMS` della cartella del backup.
6. Cartella con data e tipo, ad esempio `/srv/domuscan/produzione/backup/2026-11-14_giornaliero/`:
   - **settimanale** la domenica;
   - **mensile** il giorno 1;
   - **retention 7/4/12**: le cartelle in eccesso, per tipo, vengono eliminate.
7. **Invio remoto** con `rclone sync` verso `BACKUP_REMOTO`, solo se impostato. Per decisione 5 resta vuoto: lo script scrive l'avviso "backup solo locale" nel log e termina comunque con 0.
8. **Esito**: una riga nel log (`dati/log/backup.log`) con tipo, dimensione, durata, checksum ed esito. Codice di uscita diverso da 0 in caso di errore, così il cron lo segnala.

Opzioni: `--env <file>`, `--destinazione <cartella>` (sovrascrive quella del `.env`, usata dai test), `--senza-remoto`.

### `strumenti/ripristino.sh`

Uso: `ripristino.sh --env <file> --da <cartella_backup> [--database <nome>] [--conferma]`. Passi:
1. Verifica degli `SHA256SUMS`; si ferma se non tornano.
2. Decifratura con la chiave privata GPG, che deve essere stata importata a mano per la prova.
3. Ripristino del database nel database indicato. Senza `--conferma` si rifiuta di sovrascrivere un database non vuoto.
4. Estrazione del Vault in `PERCORSO_VAULT`, che deve essere vuoto.
5. Riepilogo finale: numero di righe di `studi`, `amministratori`, `chiavi_amministratore` e `registro_audit`, da confrontare con l'origine.

### Variabili nuove in `configurazione/.env.esempio`

```
PERCORSO_BACKUP=./backup
BACKUP_GPG_DESTINATARIO=        # impronta della chiave pubblica GPG
BACKUP_REMOTO=                  # es. ovh_s3:domuscan-backup/produzione (vuoto = solo locale, decisione 5)
BACKUP_RETENTION_GIORNALIERI=7
BACKUP_RETENTION_SETTIMANALI=4
BACKUP_RETENTION_MENSILI=12
```

### Aggiornamenti

- `strumenti/verifica_ambiente.sh`: `gpg`, `gzip`, `tar` e `flock` diventano obbligatori dalla fase 1; `rclone` è un avviso.
- `test/test_verifica_ambiente.sh`: allineato ai nuovi requisiti.

### Test automatico `test/test_backup.sh`

Gira in locale su `domuscan_test`, con MariaDB avviato:
1. Crea un portachiavi GPG temporaneo (`GNUPGHOME` nella cartella temporanea) con una chiave di prova senza passphrase.
2. Prepara `domuscan_test` con le migrazioni e alcuni dati (uno studio e un amministratore con chiave).
3. `backup.sh --destinazione <tmp> --senza-remoto` deve:
   - terminare con 0;
   - creare dump, archivio e `SHA256SUMS`;
   - non lasciare file in chiaro (nessun `.sql` né `.gz` non cifrato);
   - far sì che `gpg --list-packets` riconosca i file come cifrati.
4. Svuota il database e ripristina con `ripristino.sh --conferma`: i conteggi delle tabelle devono coincidere con quelli prima del backup, e i **trigger** del registro di audit devono essere ancora presenti (un `UPDATE` sul registro deve fallire).
5. Un checksum alterato deve far fallire il ripristino.
6. **Retention**: con 10 cartelle giornaliere finte ne restano 7. Lo stesso controllo vale per le settimanali e le mensili.
7. Il ripristino su un database non vuoto senza `--conferma` viene rifiutato.
8. Con `BACKUP_REMOTO` vuoto il backup termina con 0 e nel log c'è l'avviso "backup solo locale".

Comando: `bash test/esegui_test.sh`. Se MariaDB non è avviato, il test fallisce con un messaggio chiaro, come `test_php.sh`.

### Documentazione

- `documentazione/backup.md`: la sezione "Da realizzare" diventa "Uso" (comandi, variabili, generazione della coppia di chiavi GPG e custodia della privata). Annotare che la copia fuori dalla VPS è rimandata (decisione 5).
- Nuovo `documentazione/registro_prove_ripristino.md`, con una tabella: data, backup usato, ambiente, durata, esito, note.

### Esito (13/11/2026)

Tutto implementato come descritto, con queste differenze:
- **Blocco con `mkdir` invece di `flock`.** `flock` non esiste in Git Bash su Windows, e renderlo obbligatorio avrebbe fatto fallire la verifica dell'ambiente in locale. La cartella `.backup.lock` (creazione atomica, con il PID dentro) ottiene lo stesso effetto. Un blocco lasciato da un processo terminato viene rimosso; un secondo backup in corso esce con codice `3`. `flock` quindi non è tra i requisiti di `verifica_ambiente.sh`.
- **Nuovo file `strumenti/libreria_backup.sh`**, non previsto dal piano: contiene le funzioni comuni ai due script (lettura del `.env` con le stesse regole di `configurazione.php`, percorsi, credenziali, blocco, log). Le credenziali del database passano in un file temporaneo con permessi `600` (`--defaults-extra-file`), non sulla riga di comando.
- **Nome delle cartelle con l'ora:** `AAAA-MM-GG_HHMMSS_<tipo>` invece di `AAAA-MM-GG_<tipo>`. Così due backup nello stesso giorno (quello notturno e quello preventivo della fase 3) non si scontrano.
- **Nuova opzione `--cartella-vault` in `ripristino.sh`.** Senza, la prova di ripristino della fase 4 su un database separato sarebbe rifiutata, perché il Vault reale non è vuoto.
- **Commenti del `.env.esempio` su righe separate**, perché il parser PHP non toglie i commenti a fine riga.

Test: `test_backup.sh` 29/29 superati; `test_verifica_ambiente.sh` esteso (gpg, gzip, tar, rclone facoltativo) e superato. Nella suite completa fallisce solo `test_repository.sh`, che falliva già prima (`PROJECT DOCS/`).

**Da riportare nella guida della fase 3:**
- l'utente MariaDB dell'ambiente deve avere anche il privilegio `EVENT`, perché il dump usa `--events`;
- in SSH serve `export GPG_TTY=$(tty)` per il ripristino.

---

## Fase 3 — Rilasci caricati a mano e guida della VPS (fatta il 13/11/2026, 8,5–12 h)

### Come funziona un rilascio

```
PC (Git Bash)                                     VPS (AlmaLinux)
─────────────                                     ───────────────
bash strumenti/prepara_rilascio.sh
  → rilasci/domuscan_v0.1.0.tar.gz      ──scp──►  /srv/domuscan/produzione/rilasci/
  → rilasci/domuscan_v0.1.0.tar.gz.sha256 ──scp─►
                                                  bash app/strumenti/installa_rilascio.sh \
                                                       --archivio rilasci/domuscan_v0.1.0.tar.gz
```

Sul server la cartella `app/` resta una **cartella vera**, non un collegamento simbolico. Con un collegamento i modelli della fase 1 non funzionerebbero: `Options -FollowSymLinks` in Apache, `open_basedir` (che risolve il percorso reale) e le regole SELinux su `app(/.*)?`. La versione nuova viene estratta in `rilasci/`, preparata lì e poi scambiata con `app/` con due `mv` sullo stesso filesystem. La versione precedente resta in `app_precedente/` per tornare indietro.

### 3.1 `strumenti/prepara_rilascio.sh` (sul PC, 1,5–2 h)

Uso: `bash strumenti/prepara_rilascio.sh [--versione <tag o commit>]`. Senza argomento usa `HEAD`. Passi:
1. **Controlli:**
   - albero di lavoro pulito (`git status --porcelain` vuoto), altrimenti si ferma: un pacchetto deve corrispondere a un commit preciso;
   - `composer` disponibile.
2. **Nome della versione:**
   - il tag, se il commit ne ha uno (`git describe --tags --exact-match`);
   - altrimenti `<AAAAMMGG>-<hash breve>`.
3. **Esportazione** con `git -c core.autocrlf=false archive` in una cartella temporanea. Il `-c core.autocrlf=false` evita che Git per Windows converta gli a capo in CRLF: script `.sh` con CRLF non partono su Linux. Sono **esclusi** dal pacchetto:
   - `test/`, `prototipi/`, `PROJECT DOCS/`, `documentazione/`;
   - `README.md`, `PROJECT_STATE.md`, `TODO.md`, `.gitignore`.

   Sono **inclusi**: `pubblico/`, `sorgenti/`, `database/`, `strumenti/`, `lavori/`, `configurazione/`, `composer.json`, `composer.lock`.
4. **Librerie:** `composer install --no-dev --optimize-autoloader --no-interaction` nella cartella temporanea, così `vendor/` viaggia nel pacchetto e il server non ha bisogno né di Composer né di internet.
5. File **`VERSIONE`** nella radice del pacchetto, con nome della versione, hash completo del commit e data di preparazione.
6. **Archivio** `rilasci/domuscan_<versione>.tar.gz` e file `.sha256` accanto (formato `sha256sum`).
7. Stampa i due comandi `scp` da usare e il comando di installazione.

La cartella `rilasci/` va aggiunta al `.gitignore`.

### 3.2 `strumenti/installa_rilascio.sh` (sul server, 3–4 h)

Fa parte del pacchetto stesso. Al **primo** rilascio si lancia dalla cartella estratta a mano (procedura nella guida); dai successivi da `app/strumenti/`.

Uso:
```
installa_rilascio.sh --cartella-ambiente /srv/domuscan/produzione --archivio <file.tar.gz>
installa_rilascio.sh --cartella-ambiente /srv/domuscan/produzione --torna-precedente
```

**Installazione.** Passi, nell'ordine. Ai passi 1–6 `app/` non viene toccata, quindi un errore lascia il sito com'era.
1. Controlli:
   - lo script gira come utente di servizio, non come root;
   - il checksum dell'archivio coincide con il file `.sha256`;
   - la versione è diversa da quella installata (letta da `app/VERSIONE`).
2. Estrazione in `rilasci/<versione>/`.
3. Copia di `app/.env` nella nuova cartella, con permessi `600`. Al primo rilascio, se `app/` non esiste, il `.env` viene preso da `--env <file>`.
4. **Backup preventivo** con `strumenti/backup.sh` (fase 2). Se fallisce, l'installazione si ferma.
5. **Migrazioni** con il `migra.php` della versione nuova, prima dello scambio. Le migrazioni del progetto aggiungono e non tolgono, quindi il codice vecchio continua a funzionare sullo schema nuovo per i pochi secondi dello scambio. Se una migrazione fallisce ci si ferma, e lo script stampa il comando di `ripristino.sh` con il backup appena fatto.
6. `verifica_ambiente.sh --fase 1 --ruolo server` della versione nuova.
7. **Scambio:**
   - `app_precedente/` viene eliminata;
   - `app/` diventa `app_precedente/`;
   - `rilasci/<versione>/` diventa `app/`.
8. Ricarica di PHP‑FPM (`sudo systemctl reload php-fpm`, unico comando permesso all'utente dal file `sudoers`), per svuotare l'OPcache.
9. Riga in `dati/log/rilasci.log` con data, versione installata, versione precedente ed esito. In `rilasci/` restano gli ultimi 3 archivi.

**Ritorno alla versione precedente** (`--torna-precedente`):
- scambia `app/` e `app_precedente/` e ricarica PHP‑FPM;
- **si rifiuta** se la versione attuale ha migrazioni che la precedente non conosce (confronto dei file in `database/migrazioni/`). In quel caso stampa la procedura: `ripristino.sh` con il backup fatto prima dell'installazione, poi `--torna-precedente --forza`.

**SELinux.** I file estratti ereditano l'etichetta della cartella in cui nascono, e `mv` la conserva. La guida etichetta una volta per tutte `rilasci/` come `httpd_sys_content_t` (come `app/`), così la versione nuova è già leggibile da Apache dopo lo scambio, senza `restorecon` e senza permessi di root.

### 3.3 `strumenti/verifica_ambiente.sh` (0,5–1 h)

Nuova opzione `--ruolo server`: `git` e `composer` diventano avvisi invece che requisiti obbligatori (decisioni 6 e 7). Senza l'opzione il comportamento resta quello attuale (ruolo `sviluppo`). `test/test_verifica_ambiente.sh` viene esteso con i due casi.

### 3.4 Test automatico `test/test_rilascio.sh` (2–3 h)

Tutto in una cartella temporanea, senza toccare il progetto né il database:
- **Preparazione:**
  - repository git di prova con un commit, `composer` finto nel `PATH` (crea `vendor/autoload.php`);
  - si rifiuta con albero di lavoro sporco;
  - il pacchetto contiene `VERSIONE`, `vendor/` e `pubblico/` e **non** contiene `test/`, `PROJECT DOCS/`, `TODO.md`;
  - nessun file `.sh` contiene CR;
  - il `.sha256` è valido;
  - con un tag il nome è quello del tag.
- **Installazione**, su una cartella ambiente finta, con `backup.sh`, `php` e `sudo` sostituiti da eseguibili di prova che scrivono un marcatore:
  - primo rilascio con `--env`, poi un secondo rilascio: `app/VERSIONE` è quella nuova, `app_precedente/VERSIONE` quella vecchia, `.env` presente in `app/`;
  - checksum alterato: rifiutato, `app/` invariata;
  - backup che fallisce: rifiutato, `app/` invariata, migrazioni non eseguite;
  - migrazione che fallisce: rifiutato, `app/` invariata;
  - stessa versione già installata: rifiutata;
  - `--torna-precedente`: le versioni si scambiano;
  - `--torna-precedente` con una migrazione in più nella versione attuale: rifiutato;
  - permessi `600` del `.env` controllati solo su Linux (su Windows `chmod` non ha effetto).

Comando: `bash test/esegui_test.sh`.

### 3.5 Guida `documentazione/installazione_vps.md` (1,5–2 h)

Checklist da eseguire riga per riga su **AlmaLinux 9 o 10**. Sostituisce la sezione "Staging e produzione" di `ambienti.md`, che rimanderà alla guida.
0. **Versione del sistema** (non nota al 13/11/2026). Si controlla con `cat /etc/almalinux-release` oppure `rpm -E %rhel` (stampa `9` o `10`). Dove le due versioni differiscono (modulo PHP, versione di MariaDB), la guida mostra entrambi i comandi.
1. **Primo accesso.** Utente amministrativo nel gruppo `wheel`, chiave SSH, `PasswordAuthentication no`, `PermitRootLogin no`.
2. **Protezione.** `firewalld` (ssh, http, https), `fail2ban` per SSH (da EPEL), `dnf-automatic` per gli aggiornamenti di sicurezza, fuso orario UTC, SELinux lasciato `enforcing`.
3. **Pacchetti.**
   - `httpd`, `mod_ssl`, `php-fpm` ≥ 8.3 con `php-mysqlnd`, `php-mbstring`, `php-xml`, `php-gd`, `php-intl`, `php-sodium`. Su AlmaLinux 9 serve prima `dnf module enable php:8.3`, perché la versione predefinita è la 8.0;
   - `mariadb-server`, `gnupg2`, `tar`, `gzip`, `util-linux` (`flock`), `policycoreutils-python-utils` (`semanage`);
   - già da ora quelli delle fasi successive: `poppler-utils`, `qpdf`, `tesseract` con la lingua italiana (EPEL).
4. **MariaDB.**
   - `mariadb-secure-installation`;
   - database `domuscan_produzione` in `utf8mb4`;
   - utente `domuscan_produzione@localhost` con i privilegi necessari, compreso `TRIGGER`.
5. **Utente e cartelle.**
   - utente di sistema `domuscan-produzione`;
   - cartelle `/srv/domuscan/produzione/{app,rilasci,dati/vault,dati/in_arrivo,dati/log,dati/sessioni,backup}`;
   - regole SELinux di `configurazione/server/LEGGIMI.md`, più `rilasci(/.*)?` e `app_precedente(/.*)?` come `httpd_sys_content_t`;
   - regola `sudoers` che permette all'utente di servizio solo `systemctl reload php-fpm`.
6. **`.env`.** Partendo da `configurazione/.env.esempio`, permessi `600`. Valori:
   - `DOMUSCAN_AMBIENTE=produzione`;
   - URL `https://<IP>`;
   - `EMAIL_MODALITA=file`;
   - percorsi assoluti sotto `/srv/domuscan/produzione/dati` e `PERCORSO_BACKUP=/srv/domuscan/produzione/backup`;
   - `BACKUP_REMOTO` vuoto;
   - chiave del Vault generata sul server.
7. **Chiave GPG dei backup.** Generata sul PC del responsabile; sul server si importa solo la pubblica.
8. **Primo rilascio.**
   - `prepara_rilascio.sh` sul PC, poi `scp` dell'archivio e del `.sha256` (oppure WinSCP);
   - sul server: estrazione temporanea dell'archivio e `installa_rilascio.sh --env <file>`.
9. **Certificato autofirmato** sull'IP, come da `LEGGIMI.md`.
10. **Apache e PHP‑FPM.** Copia dei modelli della fase 1 con `__AMBIENTE__` = `produzione`, `apachectl configtest`, `php-fpm -t`, `systemctl enable --now httpd php-fpm`.
11. **Cron** del backup e primo backup lanciato a mano.
12. **Rilasci successivi:** procedura breve (preparazione, `scp`, `installa_rilascio.sh`, ritorno indietro).
13. **Verifiche finali.** Vedi la fase 4.

### Altri file

- `.gitignore`: aggiungere `/rilasci/`.
- `documentazione/ambienti.md`: la sezione "Staging e produzione (VPS OVH)" rimanda a `installazione_vps.md`. La riga "Deploy" (`git pull` di un tag) viene sostituita dal rilascio caricato a mano.
- `TODO.md`: test manuali sul server nella sezione MANUAL TESTS.

**Fuori perimetro:**
- pagina di manutenzione durante lo scambio, che dura pochi millisecondi;
- rilasci automatici;
- secondo ambiente di staging.

### Esito (13/11/2026)

Tutto implementato come descritto, con queste differenze e aggiunte:
- **Controllo degli a capo in `prepara_rilascio.sh`:** oltre a `core.autocrlf=false`, lo script conta i CR negli `.sh` del pacchetto e si ferma se ne trova. Il conteggio usa `tr`, perché `grep $''` in Git Bash dà falsi positivi.
- **Permessi normalizzati nell'archivio** (`--mode u+rwX,go+rX,go-w`, proprietario 0): Apache deve poter leggere `pubblico/` qualunque siano i permessi sul PC.
- **Formato di `VERSIONE`:** righe `versione=`, `commit=` (hash completo), `preparato=` (UTC).
- **`installa_rilascio.sh`:**
  - l'archivio contiene una sola cartella `domuscan_<versione>/`;
  - se `app/` esiste vuota viene trattata come primo rilascio; se esiste non vuota ma senza `VERSIONE`, lo script si rifiuta;
  - `--env` vale anche ai rilasci successivi e sostituisce il `.env` in uso;
  - con `--torna-precedente` il `.env` in uso viene copiato nella versione precedente, perché appartiene all'ambiente e non alla versione;
  - se la ricarica di PHP‑FPM non riesce, il rilascio resta valido: lo script lo segnala e lo scrive nel log (`ricarica_php_fpm=non_riuscita`).
- **Guida:**
  - per la prova di ripristino si apre una shell dell'utente di servizio con `script`: con il solo `sudo -u` gpg non può chiedere la passphrase, perché il terminale appartiene all'amministratore;
  - `rilasci/` ha permessi `2775`, e l'amministratore è nel gruppo dell'utente di servizio per poter caricare i pacchetti con `scp`;
  - `php-fpm` si avvia già al passo 3, così la ricarica del primo rilascio riesce.
- **File toccato fuori elenco:** `configurazione/server/LEGGIMI.md`, dove due frasi rimandavano a fasi future.

Test:
- `test_rilascio.sh`: 46 asserzioni superate; la verifica dei permessi `600` è saltata su Windows, come previsto;
- `test_verifica_ambiente.sh`: esteso con il ruolo server (git e composer assenti diventano avvisi; ruolo non valido rifiutato) e superato;
- suite completa: fallisce solo `test_repository.sh`, come prima (`PROJECT DOCS/`).

**Prima di caricare sul server:** `prepara_rilascio.sh` richiede l'albero di lavoro pulito. Le fasi 1–3 non sono ancora committate, e i tre PDF non tracciati in `documentazione/` vanno committati o esclusi dal `.gitignore`.

---

## Fase 4 — Esecuzione sul server (manuale, 5–7 h)

Seguire `documentazione/installazione_vps.md`. Verifiche da spuntare:

- [ ] `https://<IP>/` mostra la home; `http://<IP>/` fa redirect a HTTPS.
- [ ] `https://<IP>/.env`, `/.git/config` e `/../sorgenti/` rispondono 403 o 404, mai con il contenuto.
- [ ] Gli header della risposta contengono CSP, `X-Frame-Options: DENY` e `Server: Apache` senza versione.
- [ ] `ausearch -m avc -ts recent` non mostra dinieghi di SELinux dopo la navigazione.
- [ ] `php strumenti/migra.php` applica 001–004 senza errori sulla versione di MariaDB del server.
- [ ] Registrazione di uno studio, poi lettura del link dal file `.eml` in `dati/log/email/`, conferma, login, chiave `DSA-…` visibile e copia funzionante (test manuali della Fase 1 del TODO, ora sul server).
- [ ] Un errore forzato (ad esempio il database fermo) mostra la pagina generica, senza dettagli tecnici.
- [ ] `ssh root@<IP>` e l'accesso con password vengono rifiutati.
- [ ] Il backup manuale termina con 0, i file sono cifrati e nel log compare l'avviso "backup solo locale".
- [ ] **Prima prova di ripristino**: su un database `domuscan_ripristino` separato, con la chiave privata GPG importata temporaneamente e poi rimossa dal server. Conteggi uguali, tempo registrato in `registro_prove_ripristino.md`.
- [ ] Il giorno dopo, il log mostra il backup notturno partito da cron.
- [ ] Un secondo rilascio di prova (`prepara_rilascio.sh`, `scp`, `installa_rilascio.sh`) va a buon fine; `--torna-precedente` riporta alla versione prima.

---

## Fase 5 — HTTPS definitivo (da pianificare)

**Prerequisito:** i DNS di `domuscan.it` puntano alla VPS (a carico di altri).

Poi:
- virtual host per nome (`app.domuscan.it`, `verify.domuscan.it`);
- `certbot --apache` con rinnovo automatico;
- rimozione del certificato autofirmato;
- aggiornamento di `DOMUSCAN_URL_*` nel `.env`.

**Domanda aperta:** quali sottodomini saranno creati e chi li comunica.

---

## Osservazioni fuori piano

1. **Documenti riservati nel repository remoto.** Nel commit `6942eae` è stata tolta dal `.gitignore` la regola `/PROJECT DOCS/`, e la cartella (con il codice auth‑info del dominio, l'offerta economica e i documenti sul metodo da brevettare) è su GitHub. `test_repository.sh` fallisce per questo motivo. Il pacchetto di rilascio la esclude comunque (3.1), quindi non finisce sul server.
2. **TODO 0.8 "Acquistare la VPS OVH"** è ancora aperta: va chiusa a mano.
3. **Backup solo sulla VPS** (decisione 5): se la VPS si guasta, si perdono anche i backup. In area test è accettabile; va risolto prima di avere dati reali.
4. **Produzione usata come area di test:** prima dell'arrivo dei dati reali, il database e le cartelle `dati/` dovranno essere svuotati degli account di prova, e il registro di audit, che è append‑only, andrà ricreato da zero.
5. **MariaDB in locale** va avviato prima di `/run-plan 261113 2`, perché `test_backup.sh` ne ha bisogno.
