netgescon-day0/docker/README_VM_SETUP.md

# NetGescon Docker Pack - VM Ubuntu nuova

Questa cartella contiene tutto il necessario per preparare una nuova VM Ubuntu e avviare NetGescon con 3 domini:

- `www.netgescon.it` (presentazione)
- `app.netgescon.it` (produzione)
- `demo.netgescon.it` (demo)

## Contenuto pronto all'uso

- `docker-compose.multisite.yml`
- `.env.multisite.example`
- `nginx/prod.conf`
- `nginx/demo.conf`
- `www/index.html`
- `provision-vm.sh`
- `install-dev-tools.sh`
- `deploy-multisite.sh`
- `update-multisite.sh`
- `daemon-update-runner.sh`
- `backup-multisite.sh`

## 0) Prerequisiti DNS/Router

Prima di tutto:

1. Punta i record A dei domini verso IP pubblico della VM/linea:
   - `www.netgescon.it`
   - `app.netgescon.it`
   - `demo.netgescon.it`
2. Apri/NAT verso la VM le porte:
   - `80/tcp`
   - `443/tcp`

## 1) Preparazione VM (una volta sola)

Da repo `netgescon-laravel`:

```bash
cd /percorso/netgescon-laravel/docker
chmod +x provision-vm.sh install-dev-tools.sh deploy-multisite.sh update-multisite.sh backup-multisite.sh
chmod +x daemon-update-runner.sh
./provision-vm.sh
```

Logout/Login (o reboot) dopo `provision-vm.sh` per applicare gruppo Docker.

## 2) Opzionale: strumenti desktop VM

Se vuoi usare la VM anche come postazione operativa:

```bash
cd /percorso/netgescon-laravel/docker
./install-dev-tools.sh
```

Installa:

- VS Code
- XRDP (desktop remoto)
- ambiente desktop leggero (XFCE)

## 3) Configurazione ambiente

```bash
cd /percorso/netgescon-laravel
cp docker/.env.multisite.example docker/.env.multisite
nano docker/.env.multisite
```

Imposta almeno:

- password DB prod/demo
- email Let's Encrypt
- domini reali

## 4) Primo deploy

```bash
cd /percorso/netgescon-laravel/docker
./deploy-multisite.sh
```

## 5) Aggiornamenti online (procedura standard)

```bash
cd /percorso/netgescon-laravel/docker
./update-multisite.sh
```

## 5b) Runner daemon per update da pannello

Quando `NETGESCON_UPDATE_EXECUTOR=daemon`, il pulsante del pannello non esegue direttamente il refresh dentro l app ma scrive una richiesta in coda. Il runner host la consuma ed esegue l update multisito:

```bash
./daemon-update-runner.sh
```

Uso previsto: agganciarlo a `systemd`, `cron` o a un supervisore host che lo lanci a intervalli brevi. In questo modo l applicazione non ha bisogno di controllo shell sul nodo remoto ma puo comunque orchestrare l update Docker.

Valori consigliati in `docker/.env.multisite` per mantenere controllo manuale degli update in questa fase:

```bash
PROD_UPDATE_EXECUTOR=local
DEMO_UPDATE_EXECUTOR=local
RUN_DB_BACKUP=false
PROD_PREUPDATE_BACKUP_ENABLED=false
DEMO_PREUPDATE_BACKUP_ENABLED=false
```

La procedura fa:

1. backup DB prod + demo se `RUN_DB_BACKUP=true`
2. attiva maintenance mode Laravel su APP e DEMO con pagina 503 prerenderizzata
3. aggiorna codice in base alla modalità scelta
4. rebuild immagine app condivisa prod/demo
5. restart container applicativi
6. clean cache Laravel
7. riapre automaticamente i siti con `php artisan up`

### Pagina 503 gestita dall'applicazione

La pagina di maintenance non dipende più dal webserver di sistema: viene prerenderizzata da Laravel con `php artisan down --render=errors::503`.

La vista è in `resources/views/errors/503.blade.php` e si personalizza per APP e DEMO dai valori del file `docker/.env.multisite`:

- `PROD_SITE_LABEL`
- `DEMO_SITE_LABEL`
- `PROD_MAINTENANCE_TITLE`
- `PROD_MAINTENANCE_MESSAGE`
- `PROD_MAINTENANCE_DETAIL`
- `DEMO_MAINTENANCE_TITLE`
- `DEMO_MAINTENANCE_MESSAGE`
- `DEMO_MAINTENANCE_DETAIL`
- `MAINTENANCE_SUPPORT_EMAIL`
- `MAINTENANCE_SUPPORT_URL`

In questo modo il blocco utenti durante l'aggiornamento resta sotto controllo del progetto distribuito, senza dipendere dalla pagina 503 del sistema remoto.

### Modalità update (senza Git obbligatorio)

Nel file `docker/.env.multisite` imposta `UPDATE_MODE`:

- `local`: usa il codice già presente sulla VM (default)
- `distro`: scarica pacchetto privato autorizzato (`DISTRO_UPDATE_URL` + `DISTRO_UPDATE_TOKEN`)
- `github`: scarica pacchetto release pubblico (`GITHUB_RELEASE_URL`)

## 6) Backup manuale rapido

```bash
cd /percorso/netgescon-laravel/docker
./backup-multisite.sh

Nota operativa: nella fase attuale l update multisito puo lasciare `RUN_DB_BACKUP=false` per privilegiare velocita e affidabilita del flusso di aggiornamento. La procedura backup resta disponibile ma non viene eseguita automaticamente finche non viene consolidata.
```

Dump in:

- `storage/backups/prod_*.sql`
- `storage/backups/demo_*.sql`

## 7) Comandi utili

Stato container:

```bash
docker compose --env-file docker/.env.multisite -f docker/docker-compose.multisite.yml ps
```

Log in tempo reale:

```bash
docker compose --env-file docker/.env.multisite -f docker/docker-compose.multisite.yml logs -f --tail=200
```

Riavvio stack:

```bash
docker compose --env-file docker/.env.multisite -f docker/docker-compose.multisite.yml up -d
```

## 8) Esecuzione locale (senza server online)

Per girare tutto in locale su porte dedicate:

```bash
cd /percorso/netgescon-laravel
cp docker/.env.multisite.example docker/.env.local
docker compose --env-file docker/.env.local -f docker/docker-compose.local.yml up -d --build
```

URL locali:

- Produzione locale: `http://localhost:8080`
- Demo locale: `http://localhost:8081`
- Sito presentazione: `http://localhost:8082`

## Troubleshooting rapido

### Errore `exit code 127`

Significa quasi sempre "comando non trovato".

Controlla:

```bash
which bash
which docker || true
docker compose version || true
docker-compose --version || true
```

Se Docker manca:

```bash
cd /percorso/netgescon-laravel/docker
./provision-vm.sh
```

Se Docker c'è ma non hai permessi:

```bash
sudo usermod -aG docker $USER
newgrp docker
docker ps
```