# Ambienti di esecuzione

> Come sono organizzati gli ambienti di sviluppo, staging e produzione e come si predispongono. Decisioni di riferimento: D1 (stack), D12 (MariaDB), D9 (worker via cron), D11 (VPS OVH).

## Panoramica

| | Sviluppo | Staging | Produzione |
|---|---|---|---|
| Dove | PC dello sviluppatore | VPS OVH | VPS OVH |
| Scopo | Scrivere e provare il codice | Collaudi dei SAL, prove con il corpus pilota | Studi pilota e clienti |
| Dati | Set sintetico/anonimizzato | Corpus pilota autorizzato | Dati reali |
| URL | `http://localhost:8000` | da definire (es. `staging.domuscan.it`) | applicazione + `verify.domuscan.it` |
| `DOMUSCAN_AMBIENTE` | `sviluppo` | `staging` | `produzione` |

**Separazione:**
- staging e produzione hanno database, Vault, chiavi e file `.env` **distinti**;
- i dati di produzione non si copiano mai in sviluppo;
- le chiavi del sigillo di produzione non escono mai dal server di produzione.

Per il pilota staging e produzione possono condividere la stessa VPS, ma solo con utenti di sistema, database e cartelle separati; meglio due VPS se il budget lo consente.

## Requisiti comuni

Verificabili con `strumenti/verifica_ambiente.sh` (esce con codice 1 se manca un requisito obbligatorio). Ogni requisito diventa obbligatorio da una fase del piano pilota; con `--fase N` quelli delle fasi successive compaiono solo come avvisi:

| Requisito | Obbligatorio dalla fase |
|---|---|
| PHP ≥ 8.3 con `pdo_mysql`, `sodium`, `mbstring`, `openssl` | 1 |
| MariaDB (server; client `mariadb` e `mariadb-dump`), git, Composer (sul server, con `--ruolo server`, git e Composer sono solo avvisi), `gpg`, `gzip`, `tar` | 1 |
| Estensione `fileinfo` | 2 |
| Estensioni `dom`, `simplexml`, `libxml`; OpenSSL a riga di comando | 3 |
| Estensione `iconv`; Poppler (`pdftotext` con `-bbox`); Tesseract con lingua `ita` | 4 |
| Estensioni `zlib`, `gd`; qpdf | 5 |

```bash
bash strumenti/verifica_ambiente.sh --fase 1   # requisiti della fase in corso
bash strumenti/verifica_ambiente.sh            # tutti i requisiti (fasi 1-6)
bash strumenti/verifica_ambiente.sh --fase 1 --ruolo server   # sulla VPS: senza git e Composer
```

## Sviluppo locale (Windows)

Procedura usata sulla prima postazione (15/10/2026), senza servizi Windows né permessi di amministratore.

1. **PHP ≥ 8.3**: `winget install --id PHP.PHP.8.4 -e`. Nella cartella di installazione (`%LOCALAPPDATA%\Microsoft\WinGet\Packages\PHP.PHP.8.4_…`) copiare `php.ini-development` in `php.ini`, impostare `extension_dir = "ext"` e abilitare `pdo_mysql`, `sodium`, `mbstring`, `openssl`, `fileinfo`, `gd`, `curl` (usata dal test end‑to‑end) e `intl`. Se nel `PATH` c'è un'altra versione di PHP, la cartella dell'8.4 deve venire prima.
2. **MariaDB** (pacchetto ZIP portabile, versione LTS 12.3): scaricarlo da mariadb.org, verificarne lo SHA‑256 ed estrarlo in `%LOCALAPPDATA%\Programs\`. Inizializzare la cartella dei dati e avviare il server:
   ```bash
   mariadb-install-db.exe --datadir="%LOCALAPPDATA%\mariadb_dati" --password=<password_root> --port=3306
   mariadbd.exe --defaults-file="%LOCALAPPDATA%\mariadb_dati\my.ini" --console
   ```
   Il server resta attivo finché il processo è aperto; per averlo come servizio di Windows usare l'installer MSI di MariaDB.
3. **Database e utente** (con il client `mariadb -uroot -p`):
   ```sql
   CREATE DATABASE domuscan CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE DATABASE domuscan_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'domuscan'@'localhost' IDENTIFIED BY '<password>';
   CREATE USER 'domuscan'@'127.0.0.1' IDENTIFIED BY '<password>';
   GRANT ALL PRIVILEGES ON domuscan.* TO 'domuscan'@'localhost', 'domuscan'@'127.0.0.1';
   GRANT ALL PRIVILEGES ON domuscan_test.* TO 'domuscan'@'localhost', 'domuscan'@'127.0.0.1';
   ```
4. **Composer**: installer ufficiale da getcomposer.org (verificando l'hash SHA‑384), poi `composer install` nella root del progetto per scaricare PHPMailer (D10).
5. Aggiungere al `PATH` utente le cartelle `bin` di MariaDB e quella di Composer.
6. Copiare `configurazione/.env.esempio` in `.env` nella root e compilarlo (almeno `DB_PASSWORD`).
7. Applicare le migrazioni: `php strumenti/migra.php` (database di sviluppo). I test preparano da soli il database di test.
8. Eseguire `bash strumenti/verifica_ambiente.sh --fase 1`: deve terminare con 0 requisiti mancanti.
9. Avviare il server di sviluppo con `php -S localhost:8000 -t pubblico`. In sviluppo le email (conferma, recupero password) non partono: sono scritte come file `.eml` in `dati/log/email/`.

**Dalla Fase 4** servono anche:
- Poppler per Windows, con la cartella `bin` nel `PATH` **prima** di quella di Git: Git per Windows include un `pdftotext` di Xpdf, che non supporta `-bbox`;
- qpdf e Tesseract (con i dati della lingua italiana) nel `PATH`.

## Staging e produzione (VPS OVH)

La procedura completa, da eseguire riga per riga sulla VPS (AlmaLinux 9 o 10), è in [installazione_vps.md](installazione_vps.md). I modelli di configurazione di Apache, PHP‑FPM e cron sono in `configurazione/server/`.

Situazione al 13/11/2026 (piano 261113):
- sulla VPS c'è **solo l'ambiente di produzione** (`/srv/domuscan/produzione/`), usato per ora come area di test. Prima dei dati reali va svuotato degli account di prova e il registro di audit va ricreato da zero;
- finché il dominio non punta alla VPS si lavora sull'IP, con un certificato autofirmato. HTTPS serve comunque: fuori dallo sviluppo l'applicazione invia HSTS e marca il cookie di sessione come `Secure`.

Punti fissi:
- **Utente di servizio** dedicato (`domuscan-<ambiente>`), proprietario del codice e delle cartelle dei dati. Apache serve solo `app/pubblico/`.
- **Cartelle dei dati** fuori dalla document root: `/srv/domuscan/<ambiente>/dati/{vault,in_arrivo,log,sessioni}` e `/srv/domuscan/<ambiente>/backup`.
- **Segreti:** `.env` con permessi `600`, chiave privata del sigillo in un file separato con permessi `400`, chiave del Vault generata sul server.
- **Rilascio:** il server non ha accesso al repository e non ha né git né Composer. Il pacchetto si prepara sul PC con `strumenti/prepara_rilascio.sh` (contiene già `vendor/`), si carica a mano con `scp` e si installa con `strumenti/installa_rilascio.sh`, che fa il backup preventivo, applica le migrazioni e permette di tornare alla versione precedente. L'utente del database deve poter creare trigger (`TRIGGER`) e fare il dump degli eventi (`EVENT`); con il log binario attivo serve anche `log_bin_trust_function_creators=1`.
- **Cron:** backup notturno (vedi [backup.md](backup.md)) e, dalle fasi successive, worker della coda dei job (`lavori/`).
- **Email:** per ora `EMAIL_MODALITA=file` (i messaggi si leggono in `dati/log/email/`). Con una casella autenticata: `EMAIL_MODALITA=smtp` e i parametri `SMTP_*` (porta 587 con STARTTLS o 465 con SMTPS).
- **HTTPS definitivo:** certificati Let's Encrypt quando il DNS di `domuscan.it` punterà alla VPS (fase 5 del piano 261113).
- **Monitoraggio minimo:** raggiungibilità di `verify.domuscan.it`, spazio disco, esito dei backup, errori nei log.

## Gestione dei segreti

- Nessun segreto nel repository: `.env`, chiavi e dump sono esclusi dal `.gitignore`.
- `configurazione/.env.esempio` contiene solo i nomi delle variabili, con i valori segreti vuoti.
- Ogni ambiente ha segreti propri; la rotazione delle chiavi va documentata nel registro operativo.
