# JM - Installare e aggiornare

Mettere in funzione ADSWnext e tenerlo aggiornato.

**Cosa ci guadagni.** Un aggiornamento è un clic, e si ricostruisce solo ciò che è cambiato.

# JM1 - A cosa serve

# JM1.1 - Dal codice al server

**In una frase.** Una modifica approvata arriva sul server di prova con un clic, e si ricostruiscono solo i servizi che sono cambiati davvero.

ADSWnext non è un programma solo: è fatto di più servizi, ognuno con il suo compito. Aggiornarli a mano, uno per uno, vorrebbe dire ricordarsi ogni volta l'ordine, i comandi e le impostazioni. Basta una dimenticanza per lasciare il server a metà.

Per questo il lavoro lo fa la **pipeline**: una sequenza di passi automatici che parte ogni volta che una modifica entra nella versione principale del codice. Prova le parti cambiate, prepara i servizi nuovi e poi si ferma ad aspettare. L'ultimo passo, mettere i servizi nuovi al posto dei vecchi, parte solo quando una persona preme un pulsante.

<div drawio-diagram="2807"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/dal-pc-di-chi-sviluppa-al-server-di-prova-la-pipeline-prova-ricostruisce-e-aspetta-il-clic.png" alt="Dal PC di chi sviluppa al server di prova: la pipeline prova, ricostruisce e aspetta il clic"/></div>

*Dal PC di chi sviluppa al server di prova: la pipeline prova, ricostruisce e aspetta il clic*

<p class="callout success">**Cosa ci guadagni.**  
• **Un aggiornamento è un clic.** Nessuno si collega al server per digitare comandi. La pipeline fa sempre gli stessi passi, nello stesso ordine, e lascia scritto cosa ha fatto.  
• **Si ricostruisce solo ciò che è cambiato.** Se la modifica tocca solo le pagine, si rifà solo l'app web. Una modifica alla sola documentazione non ricostruisce niente.  
• **Chi non è toccato non si ferma.** I servizi rimasti uguali restano accesi. Chi sta lavorando nelle maschere storiche non perde la sessione per un aggiornamento che riguarda le stampe. </p>

Oggi l'installazione che la pipeline tiene aggiornata è una: il **server di prova**, dove si guarda il lavoro prima di portarlo altrove. Una seconda installazione accanto a quella e la distribuzione ai clienti sono ancora da fare: c'è un piano approvato, non ancora realizzato.

Questo libro racconta cosa gira sul server di prova, come arriva un aggiornamento, come si controlla che sia andato bene e cosa si può fare quando non va.

<p class="callout info">**Per chi sviluppa.**  
• La pipeline è il file `.gitlab-ci.yml`, in radice. Gira solo sulla versione principale (`main`), su un runner installato sul server di prova: costruisce ed esegue tutto lì, con Docker.  
• Lo stack è `devops/deploy/docker-compose.deploy.yml`; la spiegazione completa è `devops/deploy/README.md`.  
• Il piano per i clienti è `docs/devops/PIANO-DISTRIBUZIONE-CLIENTI.md`: immagini da un registro, un file di installazione, un comando unico. Non è ancora iniziato. </p>

# JM1.2 - Dove sta nella mappa

**In una frase.** Installare e aggiornare non è una tessera della mappa: è il lavoro che mette sul server quasi tutte le tessere e le tiene alla versione giusta.

Gli altri libri raccontano un componente. Questo racconta come i componenti arrivano sul server. Per questo sulla mappa non c'è un punto da indicare: ci sono le parti che la pipeline costruisce e riaccende, e quelle che non tocca.

<div drawio-diagram="2808"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/la-mappa-di-adswnext-accese-le-parti-che-la-pipeline-installa-e-aggiorna-sul-server-di-prova.png" alt="La mappa di ADSWnext: accese le parti che la pipeline installa e aggiorna sul server di prova"/></div>

*La mappa di ADSWnext: accese le parti che la pipeline installa e aggiorna sul server di prova*

**Cosa installa e aggiorna.** L'app web, con le pagine nuove e le pagine storiche. Il Gateway e il Monitor servizi. I servizi delle Novità: ADEnext, che contiene anche Analytics, SIGEAnext e GPEnext. Il Ponte col COBOL e Macro/Workflow SBH. L'Assistente dei dati, con il suo archivio dei Dati spiegati.

**Cosa non tocca.** L'Accesso, che controlla utente e password, sta su un altro server. L'ERP legacy/COBOL è il gestionale di sempre: resta dov'è. Gli archivi delle Schermate salvate, dei Modelli di stampa e dei Dati aziendali stanno su un database esterno: i servizi ci si collegano, la pipeline non li sposta e non li ricrea.

**Chi la fa partire.** Chi sviluppa, quando una modifica approvata entra nella versione principale del codice. E chi preme il pulsante dell'ultimo passo.

**Cosa vuol dire per te.** Se usi il gestionale, di un aggiornamento vedi solo due cose: per circa un minuto qualche pagina può dare un errore, poi trovi le funzioni nuove. I tuoi dati non si muovono: stanno negli archivi, fuori da ciò che viene ricostruito.

<p class="callout info">**Per chi sviluppa.**  
• I servizi accesi sul server di prova sono quelli della variabile `PROFILI_CLASSICO` in `.gitlab-ci.yml`.  
• Analytics non è un servizio a parte: sta dentro ADEnext e si aggiorna con lui.  
• Nel compose di installazione non c'è nessun database dei servizi: è esterno. Fa eccezione l'archivio dell'Assistente dei dati, che è un contenitore dello stack con un volume suo.  
• L'Accesso (Keycloak) si raggiunge con gli indirizzi scritti nel file delle impostazioni: vedi il libro JB - Accesso e permessi. </p>

# JM2 - Il server di prova

# JM2.1 - Cosa gira e dove

**In una frase.** Sul server di prova girano l'app web e i servizi di ADSWnext, ognuno nel suo contenitore; archivi, Accesso e gestionale di sempre stanno fuori e ci si collegano.

Il server di prova è il posto dove si guarda il lavoro finito prima di portarlo altrove. Sapere cosa c'è sopra serve a due cose: capire cosa cambia con un aggiornamento e sapere dove guardare quando una pagina non risponde.

<div drawio-diagram="2809"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/dentro-il-server-di-prova-i-servizi-per-gruppo-fuori-gli-archivi-laccesso-e-lerp-legacycobol.png" alt="Dentro il server di prova i servizi per gruppo; fuori gli archivi, l&#039;Accesso e l&#039;ERP legacy/COBOL"/></div>

*Dentro il server di prova i servizi per gruppo; fuori gli archivi, l'Accesso e l'ERP legacy/COBOL*

Ogni servizio gira in un **contenitore**: una scatola chiusa con dentro il programma e tutto ciò che gli serve. Le scatole si accendono, si spengono e si sostituiscono una per una, senza toccare le altre.

<table id="bkmrk-gruppo-della-mappa-c"><thead><tr><th>Gruppo della mappa</th><th>Cosa gira sul server</th></tr></thead><tbody><tr><td>App web</td><td>Una sola pagina con due parti: pagine nuove e pagine storiche</td></tr><tr><td>Ingresso e controlli</td><td>Gateway e Monitor servizi</td></tr><tr><td>Novità</td><td>ADEnext (con Analytics), SIGEAnext, GPEnext con il suo servizio di impaginazione</td></tr><tr><td>Gestionale storico</td><td>Ponte col COBOL e Macro/Workflow SBH</td></tr><tr><td>Strato agentico</td><td>Assistente dei dati e il suo archivio, i Dati spiegati</td></tr></tbody></table>

**Cosa sta fuori.** Gli archivi delle Schermate salvate, dei Modelli di stampa e dei Dati aziendali sono su un database esterno. L'Accesso è su un altro server. L'ERP legacy/COBOL è il gestionale di sempre, raggiunto dal Ponte col COBOL.

**Chi si vede da fuori.** Dal tuo PC raggiungi solo l'app web e il Gateway. Gli altri servizi rispondono solo dentro il server: in mezzo c'è sempre il Gateway.

**Cosa resta dopo un aggiornamento.** I contenitori si sostituiscono, i dati no. Quello che i servizi tengono su file, come le viste delle tabelle salvate dagli utenti, sta in spazi separati che sopravvivono al cambio del contenitore.

<p class="callout info">**Nota.** GPEnext e il suo servizio di impaginazione sono entrati fra i servizi accesi dalla pipeline a novembre 2026. L'Assistente dei dati gira, ma la chat si accende con un interruttore a parte: vedi il libro JJ - Strato agentico.</p>

<p class="callout info">**Per chi sviluppa.**  
• Servizi e profili: `devops/deploy/docker-compose.deploy.yml`. Ogni servizio ha un profilo; quelli accesi li decide la pipeline (`PROFILI_CLASSICO`), non il file delle impostazioni.  
• Le porte dei servizi interni sono pubblicate solo sul server stesso (`PORTE_INTERNE_BIND`). Davanti all'app web e al Gateway va messo un proxy con HTTPS.  
• Dati su file: volumi `sbh_data`, `sigea_data`, `sbh_flow_data`, `gpe_output`, più quelli dell'Assistente dei dati. Spegnere lo stack con l'opzione che rimuove i volumi li cancella.  
• Nella pipeline ci sono anche lavori per prodotti che non fanno parte di questa raccolta. </p>

# JM2.2 - Il file delle impostazioni

**In una frase.** Tutto ciò che cambia da un'installazione all'altra, comprese le password, sta in un solo file sul server, fuori dal codice.

Il codice è uguale per tutti. Quello che cambia da un server all'altro sono gli indirizzi, le cartelle e le password. Se stessero nel codice, chiunque lo legga li vedrebbe, e ogni installazione vorrebbe una copia diversa del programma. Per questo stanno in un file a parte, che vive solo sul server.

Nel codice c'è il **modello** del file: l'elenco dei nomi, con le spiegazioni e senza i valori. Sul server c'è la **copia compilata**, con i valori veri. La pipeline e i servizi leggono quella.

Dentro trovi, per gruppi:

<table id="bkmrk-cosa-dice-esempi-di-"><thead><tr><th>Cosa dice</th><th>Esempi di nomi</th></tr></thead><tbody><tr><td>Dove sono gli archivi e con quale utente</td><td>`ADE_DB_URL`, `GPE_DB_URL`, `SIGEA_DB_URL`, con i loro `_USER` e `_PASSWORD`</td></tr><tr><td>Come si controlla chi entra</td><td>`AUTH_ENABLED`, `KEYCLOAK_BASE_URL`, `SSO_REDIRECT_ORIGINS`</td></tr><tr><td>Dove sta il gestionale di sempre</td><td>`SBH_HOST`, `SBH_PORT`, `SBH_ALLOWED_ORIGINS`</td></tr><tr><td>Le cartelle dei dati per le stampe</td><td>`GPE_DATA_DIR`, `GPE_FONT_DIR`, `GPE_CATALOGO_HOST_DIR`</td></tr><tr><td>L'Assistente dei dati</td><td>`SIGEAGENT_ENABLED` e le sue password</td></tr><tr><td>Le porte da cui si entra</td><td>`FRONTEND_PORT`, `GATEWAY_PORT`</td></tr></tbody></table>

Tre regole valgono sempre.

- **Nel modello un valore vuoto è un segreto.** Va chiesto a chi gestisce il server e scritto solo nella copia sul server. Nel modello non si scrive mai un valore vero.
- **Alcune righe sono obbligatorie.** `AUTH_ENABLED` va scritta, con `true` o `false`: se manca, ogni comando si ferma e dice cosa manca. Spegnere il controllo di chi entra deve essere una scelta scritta, non una dimenticanza.
- **Una riga cambiata vale dal deploy successivo.** Il servizio che la legge viene riacceso con il valore nuovo. Gli altri restano accesi.

<p class="callout warning">**Attenzione.** Questo file non entra mai nel codice, in una chat o in un documento. Se serve mostrarlo a qualcuno, si mostrano i nomi, non i valori.</p>

<p class="callout info">**Per chi sviluppa.**  
• Il modello è `devops/deploy/env.simil-prod.example`. Il registro di tutte le variabili, con il significato e il valore predefinito, è `docs/devops/ENVIRONMENT.md`: ha anche l'elenco dei controlli da fare prima di un deploy.  
• Quali servizi si accendono non sta in questo file: lo decide la pipeline. Una variabile d'ambiente del lavoro vince sul file.  
• Una variabile nuova si aggiunge insieme: al modello, al registro e agli avvisi (vedi [Avvisi per chi aggiorna](https://gsdoc.genesyssoftware.eu/link/37917)). </p>

# JM2.3 - Accendere un servizio nuovo

**In una frase.** Un servizio nuovo si aggiunge con poche righe e senza toccare gli altri; prima del deploy, però, sul server deve esserci già quello che gli serve per partire.

Aggiungere un servizio non vuol dire rifare l'installazione. Ogni servizio è una scatola a sé, con un'etichetta che dice se va acceso. L'esempio più recente è GPEnext, il servizio delle stampe: a novembre 2026 è entrato fra quelli che la pipeline costruisce e accende.

1. **Descrivi il servizio nello stack.** Un blocco che dice da quale cartella del codice si costruisce, quali impostazioni legge e con quale etichetta si accende.
2. **Dillo alla pipeline.** L'etichetta va aggiunta all'elenco dei servizi da costruire e a quello dei servizi da accendere. Da quel momento il servizio ha anche la sua impronta: si ricostruisce solo quando cambia.
3. **Prepara il server, prima del deploy.** È il passo che si dimentica. Per GPEnext servono tre cose:
    
    
    - l'archivio dei Modelli di stampa e il suo utente, creati una volta sul database. Le tabelle le crea il servizio da solo al primo avvio;
    - nel file delle impostazioni le tre righe dell'archivio: `GPE_DB_URL`, `GPE_DB_USER`, `GPE_DB_PASSWORD`;
    - le cartelle dei dati GPE sul server, leggibili dal servizio: dati, caratteri di stampa, catalogo dei modelli di base.
4. **Dai una rotta al Gateway.** Senza, le pagine non sanno come raggiungerlo: vedi il libro JC - Gateway e Monitor servizi, pagina «JC4.1 - Aggiungere una rotta».
5. **Fai il deploy e controlla.** Il servizio nuovo deve comparire acceso e in salute: vedi [Controllare che sia andato tutto bene](https://gsdoc.genesyssoftware.eu/link/37914).

<p class="callout warning">**Attenzione.** Se le righe dell'archivio mancano, GPEnext non parte e continua a riprovare a vuoto. Il resto del gestionale lavora come prima: non vanno solo le stampe.</p>

<p class="callout info">**Nota.** Per importare i modelli del gestionale storico non basta che GPEnext sia acceso. Nella cartella dei dati GPE devono esserci i vecchi modelli, nella sottocartella `local/model`. Se manca, la finestra di importazione lo dice e non elenca niente: vedi il libro JK - GPEnext, pagina «JK6.1 - Importare i modelli legacy».</p>

Per spegnere un servizio non basta togliere l'etichetta: il deploy non ferma i servizi usciti dall'elenco. Vanno fermati a mano, una volta. I loro dati restano.

<p class="callout info">**Per chi sviluppa.**  
• Blocco del servizio: `devops/deploy/docker-compose.deploy.yml`, con `profiles:`. Pipeline: il profilo in `PROFILI_CLASSICO` e `PROFILI_TUTTI`, e una riga `costruisci` nel lavoro `build:images` di `.gitlab-ci.yml`.  
• GPEnext: profilo `gpe-next`, che accende anche il servizio di impaginazione. Cartelle: `GPE_DATA_DIR`, `GPE_FONT_DIR`, `GPE_CATALOGO_HOST_DIR`. Passi completi in `devops/deploy/README.md`, paragrafo 3.7.  
• L'Assistente dei dati ha i suoi passi nel paragrafo 3.6: senza le sue password il deploy si ferma prima di toccare qualunque servizio, e dice quale manca.  
• Compose e pipeline sono file protetti: li modifica una persona, non un automatismo. </p>

# JM3 - Aggiornare

# JM3.1 - La pipeline passo per passo

**In una frase.** Dopo che una modifica entra nella versione principale, la pipeline la prova, ricostruisce solo i servizi cambiati e aspetta il clic di una persona per metterli sul server di prova.

Un aggiornamento fatto a mano dipende da chi lo fa e da quanto è di fretta. La pipeline fa sempre gli stessi passi, e li fa uguali ogni volta. Il passo che cambia davvero ciò che gli utenti vedono resta in mano a una persona: lo decide lei, quando è il momento giusto.

1. **La modifica entra nella versione principale.** Chi sviluppa lavora su un ramo a parte. Quando la modifica è approvata viene unita alla versione principale, e la pipeline parte da sola. Sui rami a parte non parte niente.
2. **Test.** Vengono provate le parti toccate: se cambia ADEnext girano i suoi test, se cambia l'app web girano i controlli delle pagine. Se non cambia nessuna delle due, questo passo non parte.
3. **Build.** Per ogni servizio la pipeline calcola un'**impronta** di ciò che lo compone. Se l'impronta è uguale a quella già presente sul server, il servizio non si ricostruisce. Se è diversa, si prepara la versione nuova. Fin qui sul server non è cambiato niente: gli utenti lavorano ancora con la versione di prima.
4. **Deploy: il pulsante.** La pipeline si ferma e mostra un pulsante. Chi lo preme mette le versioni nuove al posto delle vecchie. Vengono riaccesi solo i servizi con l'impronta cambiata, o con un'impostazione cambiata. Gli altri restano accesi.
5. **I servizi ripartono.** Ogni servizio riacceso, all'avvio, porta il suo archivio alla forma che gli serve e poi si iscrive al Monitor servizi. Ci vuole circa un minuto.

<div drawio-diagram="2810"><img src="https://gsdoc.genesyssoftware.eu/uploads/images/drawio/2026-11/una-modifica-alle-sole-pagine-la-pipeline-ricostruisce-lapp-web-e-lascia-accesi-gli-altri-servizi.png" alt="Una modifica alle sole pagine: la pipeline ricostruisce l&#039;app web e lascia accesi gli altri servizi"/></div>

*Una modifica alle sole pagine: la pipeline ricostruisce l'app web e lascia accesi gli altri servizi*

<p class="callout warning">**Attenzione.** Il clic va dato in un momento tranquillo se l'aggiornamento tocca il Ponte col COBOL: riaccenderlo chiude le sessioni aperte nelle maschere storiche, e il lavoro non confermato si perde. Se il Ponte non è cambiato resta acceso, e nessuno se ne accorge.</p>

<p class="callout info">**Nota.** Oggi i test avvisano ma non bloccano: se sono rossi il pulsante compare lo stesso. Prima di premerlo, guarda l'esito dei test. Una schermata della pipeline non è ancora in questa raccolta.</p>

<p class="callout info">**Per chi sviluppa.**  
• File: `.gitlab-ci.yml`. Stadi: `test`, `helper`, `build`, `deploy`, `reconcile`. Il lavoro di build è `build:images`, quello di deploy è `deploy:simil-prod` (`when: manual`).  
• L'impronta è un tag di contenuto (`ADE_NEXT_TAG`, `GPE_NEXT_TAG`, `FRONTEND_TAG`…): l'hash degli alberi git di ciò che entra nell'immagine. Stesso contenuto, stesso tag: niente build, e il deploy non ricrea il contenitore. Dettagli in `devops/deploy/README.md`, paragrafo 3.3.  
• I test hanno ancora `allow_failure: true`: il file spiega perché e quando va tolto.  
• `reconcile` parte subito dopo l'unione, senza aspettare il clic: dice ad ADEnext quale codice generato è nella versione principale.  
• Prima di toccare i servizi, il deploy controlla che nel file delle impostazioni ci siano le password dell'Assistente dei dati: se mancano si ferma e dice quale. </p>

# JM3.2 - Controllare che sia andato tutto bene

**In una frase.** Dopo il clic si aspetta circa un minuto, poi si guarda lo stato dei servizi e si prova una cosa per ogni servizio aggiornato.

Il pulsante verde non basta. Dice che i servizi nuovi sono stati accesi, non che rispondono. Un servizio può partire e fermarsi subito dopo, per esempio perché non trova il suo archivio. Cinque minuti di controllo evitano che se ne accorga un utente il giorno dopo.

1. **Leggi la fine del lavoro di deploy.** L'ultima cosa che scrive è l'elenco dei servizi con il loro stato. Subito dopo l'accensione è normale leggere «sta partendo».
2. **Aspetta circa un minuto.** I servizi riaccesi devono avviarsi e iscriversi al Monitor servizi. Intanto l'app può mostrare «Errore server 503» sulle pagine che li usano. Non è un guasto: passa da solo. I servizi più grossi, come ADEnext e GPEnext, possono metterci un po' di più.
3. **Apri l'app ed entra.** Se la pagina di accesso si apre e ti lascia entrare, l'app web e il Gateway rispondono.
4. **Prova una cosa per ogni servizio aggiornato.**
    
    
    - SIGEAnext: apri una tabella con i dati del gestionale.
    - ADEnext: apri una schermata disegnata o un cruscotto.
    - GPEnext: chiedi una stampa in PDF.
    - Ponte col COBOL: apri una maschera storica.
5. **Se una prova non va, guarda chi manca.** Sul server, la pagina del Monitor servizi elenca i servizi iscritti. Chi non c'è non è partito: il motivo è scritto nel suo registro. Vedi il libro JC - Gateway e Monitor servizi, pagina «JC3.1 - Vedere quali servizi sono accesi».
6. **Guarda che il resto non si sia mosso.** I servizi che non erano cambiati devono risultare accesi da prima dell'aggiornamento. Se sono ripartiti anche loro, qualcosa li ha toccati: di solito un'impostazione cambiata.

<p class="callout info">**Nota.** Un servizio che si ferma viene riacceso da solo. Per questo un servizio a cui manca un'impostazione non resta spento: continua a ripartire a vuoto, e nell'elenco lo vedi tornare sempre «sta partendo».</p>

<p class="callout warning">**Attenzione.** L'errore 503 dopo un aggiornamento dura circa un minuto. Se dopo qualche minuto c'è ancora, e sempre sulla stessa funzione, quel servizio non è partito: vedi [Se qualcosa non va](https://gsdoc.genesyssoftware.eu/link/37918).</p>

<p class="callout info">**Per chi sviluppa.**  
• Il lavoro di deploy finisce con `docker compose ps`: stati `starting`, `healthy`, `unhealthy`.  
• Ogni servizio ha il suo controllo di stato (`/actuator/health`), che il compose interroga a intervalli. Il tempo concesso per partire va da 40 secondi (Monitor servizi) a 120 (ADEnext, GPEnext): `devops/deploy/docker-compose.deploy.yml`.  
• Gateway, SIGEAnext, GPEnext e app web aspettano che il servizio da cui dipendono sia in salute (`depends_on`).  
• Le porte interne rispondono solo dal server: il controllo di stato a mano si fa da lì.  
• Riavvio automatico: `restart: unless-stopped`. </p>

# JM3.3 - Tornare indietro

**In una frase.** Non c'è un pulsante «annulla»: si torna indietro togliendo la modifica dal codice e facendo ripartire la pipeline, e quello che è già cambiato negli archivi resta.

È meglio saperlo prima. Chi preme il pulsante del deploy deve sapere cosa può disfare e cosa no. Promettere un ritorno automatico che non esiste sarebbe peggio che non averlo.

## Quello che si può fare

**Non premere.** Finché nessuno preme il pulsante, sul server gira la versione di prima. Se i test sono rossi o la modifica non convince, si lascia la pipeline ferma lì. Non succede niente.

**Togliere la modifica e rifare il giro.** È la strada normale. Chi sviluppa annulla la modifica nel codice, l'annullamento entra nella versione principale e la pipeline riparte. Il servizio torna com'era, e si rimette sul server con lo stesso clic.

**Contare sulla versione di prima, per poco.** Quando la pipeline prepara una versione nuova, quella vecchia non viene cancellata finché un servizio acceso la sta usando. Dopo il deploy resta sul server ancora per un giro, e sparisce alla pipeline successiva. In quella finestra, se il codice torna identico a prima, l'impronta è la stessa e non serve ricostruire niente. Rimetterla in funzione a mano è un lavoro per chi gestisce il server: non c'è una procedura guidata.

## Quello che non si può fare

**Riportare indietro gli archivi.** Quando un servizio parte, porta il suo archivio alla forma che gli serve: aggiunge una tabella, una colonna. Questi passaggi vanno solo in avanti. Tornare alla versione di prima del servizio non li disfa. Se un passaggio era sbagliato, si corregge con un passaggio nuovo.

**Riavere le sessioni chiuse.** Se l'aggiornamento ha riacceso il Ponte col COBOL, le sessioni aperte nelle maschere storiche sono state chiuse. Tornare indietro lo riaccende un'altra volta.

<p class="callout warning">**Attenzione.** Prima di un aggiornamento che cambia la forma di un archivio, serve una copia dell'archivio. La pipeline non la fa.</p>

<p class="callout info">**Nota.** Il ritorno alla versione precedente, servizio per servizio e con un comando, è previsto nel piano per l'installazione dai clienti. Quel piano non è ancora realizzato.</p>

<p class="callout info">**Per chi sviluppa.**  
• Pulizia delle immagini: `build:images` toglie i tag diversi da quello attuale con `docker rmi` senza `-f`, che non tocca le immagini in uso. Vedi `devops/deploy/README.md`, paragrafo 3.3.  
• Il tag è l'hash del contenuto: un revert che riporta la cartella del servizio allo stato di prima dà lo stesso tag di prima.  
• Le migrazioni di ADEnext e GPEnext partono a ogni avvio. In ADEnext una migrazione già applicata e poi modificata non viene rieseguita: si aggiunge una migrazione nuova.  
• Gli archivi sono descritti nel libro JL - Archivi. Copie dei volumi su file: `devops/deploy/README.md`, paragrafo 3.4. </p>

# JM4 - Per chi sviluppa

# JM4.1 - Avviare tutto sul proprio PC

**In una frase.** Sul PC di chi sviluppa ADSWnext si avvia con un solo comando, che fa le domande giuste e accende i servizi scelti.

Per provare una modifica non serve il server di prova. Si accende tutto sul proprio PC, si guarda il risultato e solo dopo si propone la modifica. Il comando di avvio esiste perché i pezzi sono tanti: metterli insieme a mano, ogni volta, è il modo più facile per sbagliare.

1. **Installa Docker.** È l'unica cosa che serve davvero: i servizi girano in contenitori, come sul server di prova.
2. **Copia i file delle impostazioni dai modelli.** Nel codice ci sono solo i modelli, senza valori segreti. Le copie restano sul tuo PC e non entrano mai nel codice. Un valore vuoto nel modello è un segreto o un dato del tuo ambiente: chiedilo a chi segue il progetto.
3. **Lancia il comando di avvio.** Da Windows è `.\shell\run.ps1`. La prima volta ci mette un minuto in più, perché prepara se stesso.
4. **Rispondi alle domande.** Alla prima scegli **Tenant**: è l'installazione completa del gestionale. Poi scegli Docker, l'ambiente di sviluppo, il tipo di database dei Dati aziendali e i servizi da avviare. I servizi di base sono già spuntati.
5. **Salva la configurazione.** Alla fine puoi darle un nome e farla diventare quella predefinita. Dalla volta dopo riparti senza domande.
6. **Apri l'app.** Quando i servizi sono partiti, l'app risponde sul tuo PC alla porta 4200. In sviluppo il controllo di chi entra è spento, se non lo accendi tu.

Quando cambi il codice di un servizio non devi riavviare tutto: ci sono comandi che ricostruiscono un servizio solo.

<p class="callout warning">**Attenzione.** Il tuo PC non è il server di prova. Qui il database gira in un contenitore con dati tuoi; lì è esterno e condiviso. Una modifica alla forma di un archivio si prova sul database del proprio PC, non su quello condiviso.</p>

<p class="callout info">**Per chi sviluppa.**  
• Avvio: `shell/run.ps1` (Windows) o `shell/run.sh`. Ripartenze: `--default`, `--last`, `--last --rebuild --services <servizio>`. Guida del comando: `tools/run-cli/README.md`.  
• Modelli da copiare: `config/.env.dev.example` (la copia si chiama uguale, senza `.example`) e `backend/middleware/sigea-cop-ai/.env.example` nel suo `.env`. Il secondo è obbligatorio anche se non usi quel servizio: senza, lo stack non parte.  
• Ricostruire un servizio solo: `shell/dev-ade-rebuild.ps1`, `shell/dev-sigea-rebuild.ps1`, `shell/dev-gpe-rebuild.ps1`. Come funziona: `devops/docker/README-dev-build.md`.  
• La guida d'ingresso completa, con requisiti e ciclo di lavoro, è `docs/getting-started.md`. </p>

# JM4.2 - Avvisi per chi aggiorna

**In una frase.** Ogni cambiamento che chiede di fare qualcosa a chi aggiorna è scritto in un solo file, con la data e con le cose da fare.

Alcune modifiche non si vedono guardando il codice. Una variabile nuova da scrivere nel file delle impostazioni. Un valore predefinito cambiato. Un comando da rilanciare. Se nessuno lo dice, chi aggiorna il proprio PC o il server lo scopre dall'errore. Gli avvisi servono a dirlo prima.

Il file è un diario al contrario: l'avviso più recente sta in cima. Ogni avviso ha un titolo con la data e due parti fisse.

- **Cosa cambia.** Che cosa è diverso da prima, in poche righe.
- **Cosa fare.** I passi da fare, e dove. Quando non c'è niente da fare, c'è scritto «Niente».

Si legge in due momenti.

1. **Dopo aver scaricato il codice aggiornato.** Leggi gli avvisi dalla cima fino all'ultimo che conoscevi. Fai quello che riguarda il tuo PC.
2. **Prima di premere il pulsante del deploy.** Controlla se un avviso recente chiede qualcosa sul server: una riga nel file delle impostazioni, una cartella, un archivio da creare. Va fatto prima del clic, altrimenti il servizio nuovo non parte.

Tre esempi veri, di novembre 2026:

- la riga `AUTH_ENABLED` diventa obbligatoria nel file delle impostazioni del server: senza, ogni comando si ferma;
- GPEnext entra nella pipeline: prima del deploy vanno creati il suo archivio e le sue cartelle sul server;
- una libreria dell'app web cambia versione: dopo aver scaricato il codice va rilanciata l'installazione delle librerie.

<p class="callout success">**Cosa ci guadagni.**  
• **Niente sorprese dopo un aggiornamento.** Quello che va fatto è scritto prima, non scoperto dall'errore.  
• **Un posto solo dove guardare.** Non serve chiedere in giro né rileggere la storia delle modifiche.  
• **Il server non resta a metà.** Chi preme il pulsante sa già cosa va preparato. </p>

Chi scrive una modifica che chiede un'azione agli altri aggiunge l'avviso nello stesso momento, una voce per cambiamento. Non dopo.

<p class="callout info">**Per chi sviluppa.** La regola sta nelle istruzioni del repository: variabile nuova, valore predefinito cambiato o regola nuova vogliono una voce negli avvisi nella stessa sessione di lavoro. Le variabili vanno anche nel registro `docs/devops/ENVIRONMENT.md`.</p>

<p class="callout info">**Per approfondire.**  
• Avvisi per chi lavora sul repo, cosa fare dopo il pull: `docs/AVVISI-SVILUPPATORI.md`</p>

# JM4.3 - Se qualcosa non va

**In una frase.** I problemi più comuni di un aggiornamento, come «vedo questo, faccio questo», e le parole da sapere.

Quando un aggiornamento non va, la domanda utile è: a che passo si è fermato? Prima del clic non è cambiato niente sul server. Dopo il clic, quasi sempre il problema è un servizio solo, e quasi sempre gli manca qualcosa per partire.

## Per chi usa il gestionale

- **Vedo «Errore server 503» subito dopo un aggiornamento.** I servizi stanno ripartendo. Aspetta un minuto e riprova.
- **Dopo qualche minuto l'errore c'è ancora, su una funzione sola.** Quel servizio non è partito. Il resto puoi usarlo. Avvisa chi gestisce il server.
- **Stavo lavorando in una maschera storica e la sessione si è chiusa.** L'aggiornamento ha riacceso il Ponte col COBOL. Rientra: il lavoro non confermato va rifatto.
- **Non vedo la funzione nuova.** Ricarica la pagina. Se non c'è ancora, il pulsante del deploy forse non è stato premuto: la modifica è pronta ma non è sul server.

## Per chi fa l'aggiornamento

- **La pipeline non è partita.** Parte solo quando la modifica entra nella versione principale. Su un ramo a parte non parte niente.
- **Il build non ha ricostruito niente.** È giusto, se la modifica non tocca nessun servizio: per esempio solo documentazione.
- **Il deploy si ferma subito e nomina una password.** Mancano le righe dell'Assistente dei dati nel file delle impostazioni. Non ha toccato nessun servizio: aggiungile e premi di nuovo.
- **Ogni comando si ferma e chiede `AUTH_ENABLED`.** La riga è obbligatoria nel file delle impostazioni: scrivila, con `true` o `false`.
- **GPEnext torna sempre «sta partendo».** Mancano le righe del suo archivio: `GPE_DB_URL`, `GPE_DB_USER`, `GPE_DB_PASSWORD`. Oppure l'archivio non è stato creato.
- **GPEnext è acceso ma l'importazione dei vecchi modelli non elenca niente.** Nella cartella dei dati GPE manca la sottocartella `local/model`, o il servizio non la può leggere.
- **Un servizio che non avevo toccato è ripartito.** È cambiata una sua impostazione, o un file che entra nella sua impronta.
- **Ho tolto un servizio dall'elenco ma gira ancora.** Il deploy non spegne chi esce dall'elenco: va fermato a mano.
- **Un servizio dà 503 e non passa.** Guarda sul server la pagina del Monitor servizi e il registro del servizio: vedi il libro JC - Gateway e Monitor servizi.

Se serve tornare alla versione di prima: [Tornare indietro](https://gsdoc.genesyssoftware.eu/link/37915).

## Parole da sapere

- **Server di prova.** L'installazione dove si guarda il lavoro prima di portarlo altrove. Oggi è l'unica tenuta aggiornata dalla pipeline.
- **Versione principale.** Il codice approvato, da cui si costruisce ciò che va sul server.
- **Pipeline.** La sequenza di passi automatici: test, build, deploy.
- **Build.** Preparare la versione nuova di un servizio. Non cambia ancora niente sul server.
- **Deploy.** Mettere la versione nuova al posto della vecchia. Parte con un clic.
- **Impronta.** Il segno che dice se il contenuto di un servizio è cambiato. Uguale: non si ricostruisce.
- **Contenitore.** La scatola chiusa in cui gira un servizio, con tutto ciò che gli serve.
- **File delle impostazioni.** Il file sul server con indirizzi, cartelle e password. Non sta nel codice.
- **Migrazione.** Un passaggio che cambia la forma di un archivio. Parte da solo all'avvio del servizio e va solo in avanti.
- **Avviso.** La voce che dice cosa fare dopo un cambiamento.

<p class="callout info">**Per chi sviluppa.** Registri e stato: `docker compose ps` e `docker logs <contenitore>` sul server. I passi operativi, con la verifica di ognuno, sono in `devops/deploy/RUNBOOK-simil-prod.md`.</p>