# Migrazione VTE 25.02.2 → 26.* — una istanza alla volta

Riferimenti ufficiali (da applicare **senza** modifiche manuali al core VTE per “simulare” l’upgrade):

- [Update guide 26.04](https://usermanual.vtenext.com/books/release-note-vtenext-2604-kZ9/chapter/update-guide)
- [Installation Requirements 26.04](https://usermanual.vtenext.com/books/installation-requirements/page/installation-requirements-vtenext-2604)
- Rule workspace: [`.cursor/rules/vte-upgrade-2604.mdc`](file:///var/www/html/.cursor/rules/vte-upgrade-2604.mdc)

Prerequisiti comuni: **25.02.2** (ok), **licenza** attiva, **PHP ≥ 8.3** sull’istanza che aggiorni, backup **file + DB**, admin con **password locale** se usi update da web (no 2FA/SSO sul flusso).

---

## Ordine consigliato (dal meno al più critico)

| # | Istanza        | Path                 | URL tipico                    | File Apache principali |
|---|----------------|----------------------|-------------------------------|-------------------------|
| 1 | **vte_dev**    | `/var/www/html/vte_dev`   | `vtedev.mypantarei.net`       | `vte_dev.conf`, `vte_dev-le-ssl.conf` |
| 2 | **vteguzzini** | `/var/www/html/vteguzzini`| `vteguzzini.mypantarei.net`   | blocchi in `vtesmau.conf` / `vtesmau-le-ssl.conf` |
| 3 | **vtesmau**    | `/var/www/html/vtesmau`   | `vtesmau.mypantarei.net`      | idem (VirtualHost separato) |
| 4 | **vte2472**    | `/var/www/html/vte2472`   | `vte.mypantarei.net`          | `vte.conf`, `vte-le-ssl.conf` |

Regola: **completare** upgrade + smoke test su un’istanza prima di toccare la successiva.

---

## Fase 0 — PHP 8.3 sul server (una tantum)

```bash
sudo bash /var/www/html/server-ops/mypantarei/install-php83-fpm-vte26.sh
```

---

## Fase 0b — Apache: da handler globale 7.4 a handler **per Directory** (necessario per mescolare 7.4 e 8.3)

Se è attivo `conf-enabled/php7.4-fpm.conf`, tutte le richieste `.php` vanno al socket **7.4** e **non** puoi servire un solo VirtualHost con 8.3.

1. Dentro **ogni** `<Directory "...">` delle istanze ancora su 25 (e phpMyAdmin se presente), aggiungi **prima** di `</Directory>`:

```apache
    <FilesMatch "\.php$">
        SetHandler "proxy:unix:/run/php/php7.4-fpm.sock|fcgi://localhost/"
    </FilesMatch>
```

2. `sudo apache2ctl configtest && sudo systemctl reload apache2` — verifica che **tutte** le istanze su 7.4 funzionino ancora.

3. Disattiva il globale 7.4 e lascia solo i handler per Directory:

```bash
sudo a2disconf php7.4-fpm
sudo systemctl reload apache2
```

4. Controlla di nuovo tutti i siti VTE su 25: se qualcosa va in download `.php`, hai dimenticato il blocco `FilesMatch` in qualche `<Directory>`.

*(Dopo questa fase, per ogni istanza che porti a 26 sostituirai solo i `FilesMatch` di quell’istanza con il socket 8.3.)*

**Socket PHP 8.3:** `unix:/run/php/php8.3-fpm.sock|fcgi://localhost/`

```apache
    <FilesMatch "\.php$">
        SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
    </FilesMatch>
```

---

## Checklist per **ogni** istanza (ripeti in sequenza)

### 1. Backup

```bash
# DB (sostituisci utente/db da config.inc.php dell’istanza)
mysqldump -u … -p --single-transaction --routines --triggers NOME_DB > /root/backup-NOME_DB-$(date +%Y%m%d).sql

# Opzionale: tarball radice istanza
sudo tar czf /root/backup-vte-ISTANZA-$(date +%Y%m%d).tgz -C /var/www/html NOME_CARTELLA
```

### 2. Inventario custom (policy progetto)

- Moduli **SDK** / vtlib installabili, override in `Smarty/templates_sdk/`, eventuali patch non standard: da **ri-validare** dopo 26 ([Developers](https://usermanual.vtenext.com/books/developers), [Skill update customizations](https://usermanual.vtenext.com/books/developers/page/skill-update-customizations)).

### 3. Apache: solo quell’istanza → PHP 8.3

Nei file della tabella sopra, nei `<Directory>` relativi al path dell’istanza, sostituisci il `SetHandler` **7.4** con **8.3** come snippet sopra. Poi:

```bash
sudo apache2ctl configtest && sudo systemctl reload apache2
```

### 4. Cron: solo quell’istanza → PHP 8.3

Fino a fine upgrade e stabilizzazione, la riga crontab per quella radice deve usare PHP 8.3, ad esempio:

```text
*/5 * * * * www-data /var/www/html/server-ops/mypantarei/vte-RunCron-php83.sh /var/www/html/vte_dev
```

*(Le altre istanze restano su `vte-RunCron-php74.sh` o `USE_PHP=/usr/bin/php7.4` finché non le migr.)*

### 5. Esecuzione upgrade VTE 26 (solo procedure ufficiali)

**Percorso B (terminale, partner / `vteUpdater`):**

```bash
cd /var/www/html/<ISTANZA>
sudo -u www-data ./vteUpdater.sh
```

**Percorso A (web):** dopo login, modalità solo aggiornamento, **Start Update**; se non compare l’update: **cron** attivi e `./cron/RunCron.sh` (anche **due** volte) come da [Update from web interface](https://usermanual.vtenext.com/books/release-note-vtenext-2604-kZ9/page/update-from-web-interface).

### 6. Post 26.04 (rule `vte-upgrade-2604`)

- Login, smoke test (liste, allegati, schedulati, log).
- **Sweep `Smarty/templates_sdk/`** vs autoescape: vedi [`vte-smarty-escaping.mdc`](file:///var/www/html/.cursor/rules/vte-smarty-escaping.mdc) (HTML in chiaro in listview ⇒ spesso override SDK).

### 7. Chiusura istanza

Segna l’istanza come completata; **non** passare alla successiva se restano errori bloccanti.

---

## Secondo caso: **vteguzzini** (`vteguzzini.mypantarei.net`)

Stato attuale: **25.02.2** (build 3001), vhost in `vtesmau.conf` / `vtesmau-le-ssl.conf`.

### File preparati (già in repo)

| File | Scopo |
|------|--------|
| [`apply-vteguzzini-php83-apache.sh`](apply-vteguzzini-php83-apache.sh) | Socket `php8.3-fpm` solo su Directory `vteguzzini` |
| [`backup-vteguzzini-pre2604.sh`](backup-vteguzzini-pre2604.sh) | Dump DB + tarball pre-upgrade |
| [`install-vteguzzini-post2604-patches.php`](install-vteguzzini-post2604-patches.php) | Dopo 26: `sdk_class` AuthControllerNoVTCH + clear cache |
| `vteguzzini/custom_sdk/AuthControllerNoVTCH.php` | Bypass VTCH login (come vte_dev) |
| `vteguzzini/config/request.config.override.php` | Safe keys login per RH |

### Sequenza (root dove indicato)

```bash
# 1) Backup
sudo bash /var/www/html/server-ops/mypantarei/backup-vteguzzini-pre2604.sh

# 2) Solo vteguzzini → PHP 8.3
sudo bash /var/www/html/server-ops/mypantarei/apply-vteguzzini-php83-apache.sh
sudo apache2ctl configtest && sudo systemctl reload apache2

# 3) Cron: la riga in crontab utente root deve usare php8.3 (RunCron.sh default già 8.3)
#    */5 * * * * /var/www/html/vteguzzini/cron/RunCron.sh >> ...

# 4) Upgrade (partner vtenext)
#    In batch (-b) i pacchetti devono essere in vte_updater/packages/ oppure passati con --upd-package/--src-package.
#    Copia da vte_dev (già usati per 25.02.2 → 26.04, build 3367):
#      sudo mkdir -p /var/www/html/vteguzzini/vte_updater/packages
#      sudo cp /var/www/html/vte_dev/vte_updater/packages/vte3001-3367*.tgz /var/www/html/vteguzzini/vte_updater/packages/
#      sudo chown -R www-data:www-data /var/www/html/vteguzzini/vte_updater/packages
#    Access key con ! → apici singoli: -k '...'
#    PRIMA dell'upgrade: config/custom_sdk/scripts devono essere www-data (non pantarei),
#    altrimenti cp config/* fallisce e il rollback tar non sovrascrive i file custom.
#      sudo bash /var/www/html/server-ops/mypantarei/recover-vteguzzini-pre-reupgrade.sh
#    NON basta vteUpdater -b: dopo la copia file serve composer install (vendor del pacchetto è incompleto).
#    Usa lo script che copia files3367 + composer + schema:
sudo bash /var/www/html/server-ops/mypantarei/vte2604-upgrade-with-composer.sh /var/www/html/vteguzzini
#    (Prima: pacchetti in vte_updater/packages/ — vedi sopra — e recover-vteguzzini-pre-reupgrade.sh)
#    Alternativa solo download pacchetti: vteUpdater -b (fallirà allo schema senza composer manuale)
#    Oppure senza cache (scarica dal server, richiede conferme):
#    sudo -u www-data ./vteUpdater.sh -u 'PARTNER_USER' -k 'PARTNER_ACCESSKEY'

# 5) Post-upgrade patch (login senza error #27)
php8.3 /var/www/html/server-ops/mypantarei/install-vteguzzini-post2604-patches.php

# 6) Vendor composer se mancano pacchetti (come su vte_dev dopo upgrade)
#    cd /var/www/html/vteguzzini && sudo -u www-data composer install --no-dev
```

### Note licenza / alert aggiornamenti

- Login: stesso problema VTCH di vte_dev → override `AuthControllerNoVTCH` (rule [`vte-license-bypass.mdc`](../.cursor/rules/vte-license-bypass.mdc)).
- Alert **“Aggiornamenti importanti”** / hotfix in errore: spesso hotfix in stato `NOT_INSTALLABLE` (`files_changed`) perché ci sono modifiche locali ai file core — non è solo licenza. Su vte_dev compaiono righe in `vte_autoupdate_hotfix` con `status=40` e `reason=files_changed`.

---

## Primo caso: **vte_dev** (`vtedev.mypantarei.net`)

### Apache — handler PHP 8.3 solo su `vte_dev`

1. Se mancano pacchetti 8.3: `sudo bash /var/www/html/server-ops/mypantarei/install-php83-fpm-vte26.sh`
2. Applica patch ai vhost (idempotente):

```bash
sudo bash /var/www/html/server-ops/mypantarei/apply-vte-dev-php83-apache.sh
sudo apache2ctl configtest && sudo systemctl reload apache2
```

Se il sito risponde ancora con **PHP 7.4**, è attivo il globale `php7.4-fpm`: esegui la **Fase 0b** (handler 7.4 esplicito sulle altre istanze + `sudo a2disconf php7.4-fpm`) come in [README-vte26-one-by-one.md#fase-0b](README-vte26-one-by-one.md).

Snippet manuale: [`snippets/vte_dev-FilesMatch-php83.conf.fragment`](snippets/vte_dev-FilesMatch-php83.conf.fragment).

### Cron

Nel repo, `vte_dev/cron/RunCron.sh` usa già il default **`/usr/bin/php8.3`**. Allinea la **crontab** di sistema (se punta ancora a `php7.4` o a un altro path).

### Upgrade applicativo 26

Dopo backup DB e smoke login su **https://vtedev.mypantarei.net**:

```bash
cd /var/www/html/vte_dev
sudo -u www-data ./vteUpdater.sh
```

Oppure percorso **web** da manuale ([Update from web interface](https://usermanual.vtenext.com/books/release-note-vtenext-2604-kZ9/page/update-from-web-interface)): cron attivi, eventualmente due esecuzioni di `RunCron.sh`, poi **Start Update**.

### Post 26

Checklist punto 6 sopra + eventuale revisione `Smarty/templates_sdk/`.

---

## Riepilogo file in `server-ops/mypantarei/`

| File | Scopo |
|------|--------|
| [`apply-vte-dev-php83-apache.sh`](apply-vte-dev-php83-apache.sh) | Patch Apache solo `vte_dev` → socket `php8.3-fpm` |
| [`install-php83-fpm-vte26.sh`](install-php83-fpm-vte26.sh) | Pacchetti PHP 8.3 FPM + ini VTE |
| [`vte-RunCron-php83.sh`](vte-RunCron-php83.sh) | Cron RunCron con `php8.3` |
| [`vte-RunCron-php74.sh`](vte-RunCron-php74.sh) | Cron RunCron con `php7.4` (istanze ancora su 25) |

---

## Nota licenza / canale

`vteUpdater.sh` e il download della revisione sono per **partner vtenext**; se usi solo il canale web, prepara l’utente admin con password locale come da manuale.