# 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>