<!--
  @project       : Domuscan App
  @filename      : installazione_vps.md
  @author        : Damiano | <dagneni@gmail.com>
  @description   : Guida all'installazione dell'ambiente DOMUSCAN sulla VPS OVH (AlmaLinux 9 o 10),
                   al primo rilascio e ai rilasci successivi caricati a mano (piano 261113, fase 3).
  @creation date : 13-11-2026
  @last update   : 13-11-2026

  @version: 0.1.0
-->

# Installazione della VPS

> Checklist da eseguire riga per riga sulla VPS OVH. Contesto e scelte: [ambienti.md](ambienti.md); modelli di configurazione: `configurazione/server/LEGGIMI.md`; backup: [backup.md](backup.md).

**Situazione al 13/11/2026:**
- un solo ambiente, `produzione`, usato per ora come area di test;
- nessun dominio: si lavora sull'IP, con un certificato autofirmato;
- il server non ha accesso al repository: il codice arriva in un pacchetto preparato sul PC e caricato a mano;
- i backup restano solo sulla VPS (nessuna copia remota per ora).

**Convenzioni:**
- `<IP>` è l'indirizzo della VPS, `<admin>` l'utente amministrativo;
- i comandi con `sudo` si eseguono come `<admin>`;
- l'utente di servizio è `domuscan-produzione`: ha la shell `/sbin/nologin`, quindi i suoi comandi si lanciano con `sudo -u domuscan-produzione -H ...`.

Per comodità, nella sessione SSH:

```bash
AMB=produzione
RADICE=/srv/domuscan/$AMB
UTENTE=domuscan-$AMB
```

---

## 0. Versione del sistema

```bash
cat /etc/almalinux-release     # es. "AlmaLinux release 9.6"
rpm -E %rhel                   # 9 oppure 10
```

Dove le due versioni differiscono (PHP, MariaDB, aggiornamenti automatici) la guida mostra i comandi di entrambe.

## 1. Primo accesso

1. Entrare con l'utente creato da OVH (di solito `almalinux`), con la password ricevuta via email. Usarlo come `<admin>`, oppure crearne uno personale nel gruppo `wheel`:
   ```bash
   sudo useradd -m -G wheel <admin> && sudo passwd <admin>
   ```
2. Dal PC, copiare la propria chiave SSH: `ssh-copy-id <admin>@<IP>`. Verificare che l'accesso con la chiave funzioni **prima** di proseguire.
3. Disattivare password e root via SSH. Il file deve avere un numero basso: in `sshd_config.d/` vince la prima impostazione letta, e le immagini cloud hanno spesso un `50-cloud-init.conf` che riattiva le password.
   ```bash
   printf 'PasswordAuthentication no\nPermitRootLogin no\nKbdInteractiveAuthentication no\n' \
     | sudo tee /etc/ssh/sshd_config.d/01-domuscan.conf
   sudo sshd -t && sudo systemctl reload sshd
   ```
   Tenere aperta la sessione corrente e provare l'accesso da un secondo terminale.

## 2. Protezione di base

```bash
sudo dnf -y update
sudo timedatectl set-timezone UTC
getenforce                                  # deve essere "Enforcing": lasciarlo così

# Firewall: solo SSH, HTTP e HTTPS
sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-service=ssh --add-service=http --add-service=https
sudo firewall-cmd --reload

# fail2ban per SSH (da EPEL)
sudo dnf -y install epel-release
sudo dnf -y install fail2ban
printf '[sshd]\nenabled = true\n' | sudo tee /etc/fail2ban/jail.d/sshd.local
sudo systemctl enable --now fail2ban
```

Aggiornamenti di sicurezza automatici:

```bash
# AlmaLinux 9
sudo dnf -y install dnf-automatic
sudo sed -i 's/^upgrade_type.*/upgrade_type = security/; s/^apply_updates.*/apply_updates = yes/' /etc/dnf/automatic.conf
sudo systemctl enable --now dnf-automatic.timer

# AlmaLinux 10 (dnf5)
sudo dnf -y install dnf5-plugin-automatic
printf '[commands]\nupgrade_type = security\napply_updates = yes\n' | sudo tee /etc/dnf/automatic.conf
sudo systemctl enable --now dnf5-automatic.timer
```

Se nel pannello OVH è attivo anche il firewall di rete, deve lasciare passare le porte 22, 80 e 443.

## 3. Pacchetti

**PHP ≥ 8.3.**

```bash
# AlmaLinux 9: la versione predefinita è più vecchia
dnf module list php                          # se compare 8.3:
sudo dnf -y module reset php && sudo dnf -y module enable php:8.3
# Se 8.3 non compare, usare il repository Remi:
#   sudo dnf -y install https://rpms.remirepo.net/enterprise/remi-release-9.rpm
#   sudo dnf -y module reset php && sudo dnf -y module enable php:remi-8.3

# AlmaLinux 10: PHP 8.3 è già quello predefinito, nessun modulo da abilitare
```

Poi, su entrambe:

```bash
sudo dnf -y install httpd mod_ssl php-fpm php-cli php-mysqlnd php-mbstring php-xml php-gd php-intl php-sodium php-opcache
sudo dnf -y install mariadb-server gnupg2 tar gzip util-linux cronie policycoreutils-python-utils
# Già da ora quelli delle fasi successive del piano pilota
sudo dnf -y install poppler-utils qpdf tesseract tesseract-langpack-ita
php -v                                       # deve essere >= 8.3
sudo systemctl enable --now php-fpm crond
```

`php-fpm` va avviato subito: `installa_rilascio.sh` lo ricarica a ogni rilascio. Apache (`httpd`) si avvia al passo 10.

## 4. MariaDB

```bash
sudo systemctl enable --now mariadb
mariadb --version            # 10.5 su AlmaLinux 9, 10.11 su AlmaLinux 10
sudo mariadb-secure-installation
```

Su AlmaLinux 9 si può passare a 10.11, se disponibile come modulo (`dnf module list mariadb`), **prima** di creare i database.

Database e utente. L'utente serve due volte, `localhost` e `127.0.0.1`, perché l'applicazione si collega via TCP (`DB_HOST=127.0.0.1`). Generare una password lunga (ad esempio `openssl rand -base64 24`) e conservarla: va nel `.env`.

```sql
-- sudo mariadb
CREATE DATABASE domuscan_produzione CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'domuscan_produzione'@'localhost' IDENTIFIED BY '<password>';
CREATE USER 'domuscan_produzione'@'127.0.0.1' IDENTIFIED BY '<password>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX, REFERENCES,
      CREATE VIEW, SHOW VIEW, TRIGGER, EVENT, LOCK TABLES
  ON domuscan_produzione.* TO 'domuscan_produzione'@'localhost', 'domuscan_produzione'@'127.0.0.1';
```

Perché questi privilegi:
- `TRIGGER`: la migrazione 004 crea i trigger che rendono append‑only il registro di audit;
- `EVENT`, `LOCK TABLES`, `SHOW VIEW`: servono a `mariadb-dump` nei backup.

Se il log binario è attivo (`SHOW VARIABLES LIKE 'log_bin'` dà `ON`), serve anche `log_bin_trust_function_creators=1` in `/etc/my.cnf.d/`. Di norma è spento.

## 5. Utente di servizio e cartelle

```bash
sudo useradd --system --create-home --home-dir /var/lib/$UTENTE --shell /sbin/nologin $UTENTE
sudo usermod -aG $UTENTE <admin>        # così <admin> può caricare i pacchetti in rilasci/
# (uscire e rientrare in SSH perché il gruppo nuovo abbia effetto)

sudo mkdir -p $RADICE/{rilasci,backup,dati/{vault,in_arrivo,log,sessioni}}
sudo chown -R $UTENTE:$UTENTE $RADICE
sudo chmod 755 /srv/domuscan $RADICE
sudo chmod 2775 $RADICE/rilasci
sudo chmod 700 $RADICE/dati/sessioni $RADICE/dati/vault $RADICE/backup
```

**Non** creare `app/`: la crea il primo rilascio. L'utente di servizio deve poter scrivere in `$RADICE`, perché il rilascio scambia `app/` e `app_precedente/`.

**SELinux.** Sono le regole di `LEGGIMI.md`, più `rilasci/` e `app_precedente/`. Le versioni nuove nascono in `rilasci/` ed entrano in `app/` con `mv`, che conserva l'etichetta: così sono già leggibili da Apache, senza `restorecon` a ogni rilascio.

```bash
sudo semanage fcontext -a -t httpd_sys_content_t    "$RADICE/app(/.*)?"
sudo semanage fcontext -a -t httpd_sys_content_t    "$RADICE/app_precedente(/.*)?"
sudo semanage fcontext -a -t httpd_sys_content_t    "$RADICE/rilasci(/.*)?"
sudo semanage fcontext -a -t httpd_sys_rw_content_t "$RADICE/dati(/.*)?"
sudo restorecon -Rv $RADICE
sudo setsebool -P httpd_can_network_connect_db on
```

**sudoers.** L'utente di servizio può eseguire solo la ricarica di PHP‑FPM, che serve a svuotare l'OPcache dopo un rilascio:

```bash
echo "$UTENTE ALL=(root) NOPASSWD: /usr/bin/systemctl reload php-fpm" | sudo tee /etc/sudoers.d/$UTENTE
sudo chmod 440 /etc/sudoers.d/$UTENTE
sudo visudo -c
```

## 6. File `.env`

Dal PC: `scp configurazione/.env.esempio <admin>@<IP>:~/`. Poi sul server:

```bash
sudo install -o $UTENTE -g $UTENTE -m 600 ~/.env.esempio $RADICE/env_iniziale
php -r 'echo base64_encode(sodium_crypto_secretbox_keygen()), PHP_EOL;'   # chiave del Vault
sudo vi $RADICE/env_iniziale        # oppure nano
```

Valori da impostare, gli altri restano quelli del modello:

```ini
DOMUSCAN_AMBIENTE=produzione
DOMUSCAN_URL_APPLICAZIONE=https://<IP>
DOMUSCAN_URL_VERIFICA=https://<IP>/verifica
DB_HOST=127.0.0.1
DB_NOME=domuscan_produzione
DB_UTENTE=domuscan_produzione
DB_PASSWORD=<password del passo 4>
PERCORSO_VAULT=/srv/domuscan/produzione/dati/vault
PERCORSO_CARTELLA_SORVEGLIATA=/srv/domuscan/produzione/dati/in_arrivo
PERCORSO_LOG=/srv/domuscan/produzione/dati/log
CHIAVE_CIFRATURA_VAULT=<chiave appena generata>
PERCORSO_BACKUP=/srv/domuscan/produzione/backup
BACKUP_GPG_DESTINATARIO=<impronta del passo 7>
BACKUP_REMOTO=
EMAIL_MODALITA=file
```

Regole:
- i percorsi devono essere **assoluti**;
- i commenti vanno su righe separate: un `#` a fine riga diventerebbe parte del valore;
- la chiave del Vault va copiata anche offline, nello stesso posto della chiave privata GPG ([backup.md](backup.md)). Senza, il Vault salvato è illeggibile.

Il file viene copiato in `app/.env` dal primo rilascio. Dopo il passo 8 `env_iniziale` si elimina.

## 7. Chiave GPG dei backup

La chiave si genera sul **PC del responsabile**, non sul server (procedura in [backup.md](backup.md), sezione "Chiave GPG"). Sul server va **solo la pubblica**:

```bash
# dal PC: scp domuscan_backup_pubblica.asc <admin>@<IP>:~/
sudo -u $UTENTE -H gpg --import < ~/domuscan_backup_pubblica.asc
sudo -u $UTENTE -H gpg --list-keys            # l'impronta va in BACKUP_GPG_DESTINATARIO
```

## 8. Primo rilascio

**Sul PC:**
1. Fare il commit di tutto il lavoro. `prepara_rilascio.sh` si rifiuta se ci sono modifiche non committate o file non tracciati: il pacchetto deve corrispondere a un commit preciso.
2. Facoltativo ma consigliato: un tag, che diventa il nome della versione (`git tag v0.1.0`). Senza tag il nome è `<AAAAMMGG>-<hash breve>`.
3. Preparare e caricare il pacchetto:
   ```bash
   bash strumenti/prepara_rilascio.sh
   scp rilasci/domuscan_v0.1.0.tar.gz rilasci/domuscan_v0.1.0.tar.gz.sha256 <admin>@<IP>:/srv/domuscan/produzione/rilasci/
   ```
   In alternativa a `scp` va bene WinSCP, in modalità binaria.

**Sul server.** Al primo rilascio `app/` non esiste ancora, quindi lo script di installazione si prende dal pacchetto stesso:

```bash
V=v0.1.0
sudo -u $UTENTE -H tar -xzf $RADICE/rilasci/domuscan_$V.tar.gz -C /tmp domuscan_$V/strumenti/installa_rilascio.sh
sudo -u $UTENTE -H bash /tmp/domuscan_$V/strumenti/installa_rilascio.sh \
  --cartella-ambiente $RADICE \
  --archivio $RADICE/rilasci/domuscan_$V.tar.gz \
  --env $RADICE/env_iniziale
sudo rm -rf /tmp/domuscan_$V
sudo rm $RADICE/env_iniziale
```

Lo script, nell'ordine:
1. controlla il checksum;
2. estrae il pacchetto in `rilasci/<versione>/` e vi copia il `.env`;
3. fa un backup preventivo (il database è ancora vuoto, ma la catena del backup viene provata subito);
4. applica le migrazioni 001–004 e verifica l'ambiente con `--ruolo server`;
5. porta la versione in `app/` e ricarica PHP‑FPM.

L'esito va in `dati/log/rilasci.log`. Se un passo fallisce, `app/` non viene toccata.

## 9. Certificato autofirmato

Finché non c'è il dominio (fase 5 del piano 261113: Let's Encrypt):

```bash
sudo openssl req -x509 -newkey rsa:3072 -sha256 -days 365 -nodes \
  -keyout /etc/pki/tls/private/domuscan_$AMB.key \
  -out    /etc/pki/tls/certs/domuscan_$AMB.crt \
  -subj "/CN=<IP>" -addext "subjectAltName=IP:<IP>"
sudo chmod 600 /etc/pki/tls/private/domuscan_$AMB.key
sudo restorecon -v /etc/pki/tls/private/domuscan_$AMB.key /etc/pki/tls/certs/domuscan_$AMB.crt
```

Il certificato scade dopo un anno. Il browser mostra un avviso, da accettare a mano.

## 10. Apache e PHP‑FPM

I modelli sono già sul server, dentro il rilascio:

```bash
MODELLI=$RADICE/app/configurazione/server
sudo sh -c "sed 's/__AMBIENTE__/$AMB/g' $MODELLI/apache_domuscan.conf   > /etc/httpd/conf.d/10_domuscan_$AMB.conf"
sudo cp $MODELLI/apache_sicurezza.conf /etc/httpd/conf.d/05_domuscan_sicurezza.conf
sudo sh -c "sed 's/__AMBIENTE__/$AMB/g' $MODELLI/php_fpm_domuscan.conf > /etc/php-fpm.d/domuscan_$AMB.conf"
sudo restorecon -v /etc/httpd/conf.d/*.conf /etc/php-fpm.d/*.conf

sudo apachectl configtest           # "Syntax OK"
sudo php-fpm -t                     # "test is successful"
sudo systemctl reload php-fpm
sudo systemctl enable --now httpd
```

Controllo rapido dal server:

```bash
curl -kI https://<IP>/          # 200, header "Server: Apache" senza versione
curl -kI https://<IP>/.env      # 403 o 404
curl -I  http://<IP>/           # 301 verso https://
sudo ausearch -m avc -ts recent # nessun diniego di SELinux
```

## 11. Backup notturno

```bash
sudo sh -c "sed 's/__AMBIENTE__/$AMB/g' $MODELLI/cron_domuscan > /etc/cron.d/domuscan_$AMB"
sudo chmod 644 /etc/cron.d/domuscan_$AMB

# Primo backup lanciato a mano: deve terminare con 0
sudo -u $UTENTE -H bash $RADICE/app/strumenti/backup.sh --env $RADICE/app/.env; echo "codice $?"
sudo tail -n 3 $RADICE/dati/log/backup.log   # ESITO=ok e l'avviso "backup solo locale"
```

Il backup gira ogni notte alle 03:15 UTC. Il suo output va in `dati/log/backup_cron.log`.

## 12. Prima prova di ripristino

Si ripristina su un database e una cartella **separati**, senza toccare l'ambiente. Serve la chiave privata GPG, che sta sul server solo per la durata della prova.

```bash
# MariaDB: database di prova
sudo mariadb -e "GRANT ALL PRIVILEGES ON domuscan_ripristino.* TO 'domuscan_produzione'@'localhost', 'domuscan_produzione'@'127.0.0.1'"

# Chiave privata: dal PC con scp in ~/, poi passata all'utente di servizio
sudo install -o $UTENTE -g $UTENTE -m 600 ~/domuscan_backup_PRIVATA.asc /tmp/
shred -u ~/domuscan_backup_PRIVATA.asc

# Shell dell'utente di servizio con un terminale suo: con il solo "sudo -u",
# gpg non riesce a chiedere la passphrase (il terminale appartiene a <admin>)
sudo -u $UTENTE -H script -q -c bash /dev/null
```

Nella shell che si apre:

```bash
export GPG_TTY=$(tty)
gpg --import /tmp/domuscan_backup_PRIVATA.asc && shred -u /tmp/domuscan_backup_PRIVATA.asc
ls /srv/domuscan/produzione/backup/                     # scegliere il backup più recente
time bash /srv/domuscan/produzione/app/strumenti/ripristino.sh \
  --env /srv/domuscan/produzione/app/.env \
  --da /srv/domuscan/produzione/backup/<cartella> \
  --database domuscan_ripristino --cartella-vault /tmp/vault_ripristino
gpg --list-secret-keys --keyid-format long                # impronta della chiave
gpg --batch --yes --delete-secret-keys <impronta>
gpgconf --kill gpg-agent
rm -rf /tmp/vault_ripristino
exit
```

Poi, come `<admin>`:

```bash
sudo mariadb -e "DROP DATABASE domuscan_ripristino; REVOKE ALL PRIVILEGES ON domuscan_ripristino.* FROM 'domuscan_produzione'@'localhost', 'domuscan_produzione'@'127.0.0.1'"
sudo -u $UTENTE -H gpg --list-secret-keys      # non deve elencare nulla
```

Infine:
1. confrontare i conteggi stampati da `ripristino.sh` con quelli del database reale:
   ```bash
   sudo mariadb domuscan_produzione -e "SELECT COUNT(*) FROM studi; SELECT COUNT(*) FROM amministratori; SELECT COUNT(*) FROM chiavi_amministratore; SELECT COUNT(*) FROM registro_audit"
   ```
2. registrare la prova in [registro_prove_ripristino.md](registro_prove_ripristino.md), con la durata data da `time`.

## 13. Rilasci successivi

Sul PC:

```bash
git tag v0.2.0                                # facoltativo
bash strumenti/prepara_rilascio.sh
scp rilasci/domuscan_v0.2.0.tar.gz rilasci/domuscan_v0.2.0.tar.gz.sha256 <admin>@<IP>:/srv/domuscan/produzione/rilasci/
```

Sul server:

```bash
sudo -u domuscan-produzione -H bash /srv/domuscan/produzione/app/strumenti/installa_rilascio.sh \
  --cartella-ambiente /srv/domuscan/produzione \
  --archivio /srv/domuscan/produzione/rilasci/domuscan_v0.2.0.tar.gz
```

La versione sostituita resta in `app_precedente/`. In `rilasci/` restano gli ultimi 3 archivi.

**Tornare alla versione precedente:**

```bash
sudo -u domuscan-produzione -H bash /srv/domuscan/produzione/app/strumenti/installa_rilascio.sh \
  --cartella-ambiente /srv/domuscan/produzione --torna-precedente
```

Lo script si rifiuta se la versione attuale ha applicato migrazioni che la precedente non conosce: il database ha già lo schema nuovo, e cambiare solo il codice non basta. In quel caso stampa la procedura:
1. `ripristino.sh --conferma` con il backup fatto prima dell'installazione. Il percorso è nella riga `backup=` di `dati/log/rilasci.log`, e per il ripristino serve la chiave privata, come al passo 12;
2. `--torna-precedente --forza`.

**Se una migrazione fallisce** durante un'installazione, `app/` resta com'era, ma il database potrebbe essere stato modificato in parte. Lo script stampa il comando di ripristino con il backup appena fatto.

## 14. Verifiche finali (collaudo dell'ambiente)

- [ ] `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.
- [ ] `sudo ausearch -m avc -ts recent` non mostra dinieghi di SELinux dopo la navigazione.
- [ ] Le migrazioni 001–004 risultano applicate senza errori (`dati/log/rilasci.log` e output del primo rilascio).
- [ ] Registrazione di uno studio, poi lettura del link dal file `.eml` in `dati/log/email/`, conferma, login, chiave `DSA-…` visibile e copia funzionante.
- [ ] Un errore forzato (ad esempio `sudo systemctl stop mariadb`, poi riavviarlo) 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 (passo 12) registrata in `registro_prove_ripristino.md`.
- [ ] Il giorno dopo, `dati/log/backup.log` mostra il backup notturno partito da cron.
- [ ] Un secondo rilascio di prova va a buon fine e `--torna-precedente` riporta alla versione prima.

## Da ricordare

- **Backup solo sulla VPS:** se la VPS si guasta si perdono anche i backup. Va risolto (`BACKUP_REMOTO`) prima dei dati reali.
- **Produzione usata come area di test:** prima dei dati reali vanno eliminati gli account di prova, e il registro di audit, che è append‑only, va ricreato da zero.
- **Certificato autofirmato:** scade dopo un anno; sarà sostituito da Let's Encrypt quando il DNS punterà alla VPS.
