How to
Guida al rilascio dei servizi RPA
1. Obiettivo della guida
Questa guida descrive il processo standard per preparare, rilasciare e aggiornare i servizi RPA sviluppati dagli Automator all’interno del gruppo di lavoro.
L’obiettivo è garantire che ogni servizio venga rilasciato in modo ordinato, tracciabile, ripetibile e con il minor numero possibile di imprevisti, rispettando le best practice Python, Docker, GitLab e DevOps adottate dal gruppo RPA.
Per “rilascio di un servizio” si intende l’installazione e l’esecuzione del servizio su una macchina remota, utilizzando Docker Compose, immagini pubblicate sul registry GitLab del repository e file di configurazione specifici per ambiente.
2. Attori coinvolti
2.1 Sviluppatore / TL RPA
È il responsabile dello sviluppo del servizio e della preparazione tecnica del rilascio.
Si occupa di:
sviluppare il codice;
rispettare le best practice Python e Docker del gruppo RPA;
predisporre i file Docker Compose per i vari ambienti;
testare il servizio localmente;
buildare e pubblicare le immagini Docker, tramite CI o manualmente;
preparare il file .env per l’ambiente target;
salvare le configurazioni sensibili su Bitwarden;
aprire il ticket verso DevOps;
aggiornare il file di tracciamento Move to Prod a rilascio completato.
2.2 Team DevOps
È il team responsabile dell’installazione o aggiornamento del servizio sulle macchine remote.
Si occupa di:
ricevere il ticket di delivery o aggiornamento microservizio;
recuperare Docker Compose, file .env e allegati necessari;
installare o aggiornare il servizio sulla VM indicata;
configurare eventuali DNS richiesti;
verificare che il servizio sia avviato correttamente;
comunicare il completamento della lavorazione.
2.3 Gruppo RPA
È il gruppo proprietario del processo, delle best practice e della governance dei servizi RPA.
Si occupa di:
definire gli standard tecnici;
mantenere le convenzioni comuni;
garantire la tracciabilità dei rilasci;
condividere informazioni operative, come VM disponibili, ambienti e DNS.
3. Strumenti utilizzati
3.1 GitLab
GitLab è utilizzato per:
versionare il codice sorgente;
gestire il repository del servizio;
eseguire eventuali pipeline CI/CD;
pubblicare immagini Docker nel registry del repository;
mantenere tracciabilità di commit, versioni e tag.
3.2 Docker e Docker Compose
Docker è utilizzato per containerizzare il servizio RPA.
Docker Compose è utilizzato per definire l’esecuzione del servizio nei diversi ambienti:
locale;
sviluppo;
collaudo;
produzione.
3.3 GitLab Container Registry
Il registry GitLab del repository contiene le immagini Docker del servizio.
Negli ambienti remoti non viene rilasciato l’intero repository, ma vengono utilizzati:
il file Docker Compose dell’ambiente;
il file .env dell’ambiente;
l’immagine Docker già pubblicata sul registry;
eventuali file esterni non inclusi nell’immagine.
3.4 Bitwarden
Bitwarden è utilizzato per salvare e condividere in modo sicuro i file .env degli ambienti.
I file .env devono essere salvati nella raccolta RPA seguendo la naming convention:
env_<ambiente>_<nome_automazione>
Esempi:
env_dev_nome-automazione
env_coll_nome-automazione
env_prod_nome-automazione
3.5 Sistema di ticketing DevOps
Il sistema di ticketing DevOps è utilizzato per richiedere:
delivery di nuovi microservizi;
aggiornamento di microservizi esistenti;
modifica di file .env;
modifica di Docker Compose;
caricamento di file locali;
configurazione di DNS;
interventi sulle VM remote.
3.6 File Move to Prod
Il file Move to Prod è il file condiviso usato per tracciare le informazioni operative dei rilasci.
Contiene, tra le altre cose:
disponibilità delle VM;
ambiente di riferimento;
servizio rilasciato;
VM utilizzata;
DNS utilizzato;
eventuali note operative.
Il file è condiviso nel canale Teams del gruppo Python.
4. Struttura attesa del repository
Prima di qualunque rilascio, il repository deve rispettare le best practice Python e Docker del gruppo RPA.
4.1 Struttura del codice
Il codice applicativo deve essere contenuto all’interno della cartella:
src/
Esempio:
repository/
├── src/
│ └── ...
├── docker-compose.local.yml
├── docker-compose.dev.yml
├── docker-compose.coll.yml
├── docker-compose.prod.yml
├── .env.example
├── Dockerfile
├── pyproject.toml
└── README.md
4.2 Docker Compose richiesti
Devono essere presenti i Docker Compose relativi agli ambienti previsti:
docker-compose.local.yml
docker-compose.dev.yml
docker-compose.coll.yml
docker-compose.prod.yml
La naming convention può essere adattata agli standard effettivi del gruppo, ma deve essere coerente e facilmente riconoscibile.
4.3 Environment file
Deve essere presente almeno un file di esempio, ad esempio:
.env.example
Il file .env.example deve contenere tutte le variabili necessarie al servizio, senza valori sensibili reali.
Esempio:
APP_ENV=local
LOG_LEVEL=INFO
DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=
SECRET_KEY=
4.4 Mount dei volumi
I mount dei vari Docker Compose devono partire dalla cartella corrente del repository.
Esempio corretto:
volumes:
- ./data:/app/data
- ./logs:/app/logs
Esempio da evitare:
volumes:
- /home/user/project/data:/app/data
I path assoluti locali non devono essere usati nei Compose destinati al rilascio, perché non sono portabili tra ambienti e macchine diverse.
4.5 Immagini Docker
Nei Compose degli ambienti remoti non deve essere necessario buildare il codice dal repository completo.
L’ambiente remoto deve usare immagini già pubblicate sul registry GitLab.
Esempio:
services:
automazione:
image: registry.gitlab.com/gruppo/progetto/nome-servizio:dev-latest
env_file:
- .env
Oppure, in base alla strategia di versionamento:
services:
automazione:
image: registry.gitlab.com/gruppo/progetto/nome-servizio:v1.2.3
4.6 Label per Continuous Delivery
Se il servizio deve essere aggiornabile automaticamente tramite CD, il Compose deve includere le label previste dallo standard del gruppo.
Le label devono permettere al sistema di riconoscere:
servizio;
ambiente;
immagine da monitorare;
strategia di aggiornamento.
Esempio indicativo:
labels:
- "rpa.cd.enabled=true"
- "rpa.cd.environment=dev"
- "rpa.cd.service=nome-automazione"
Le label effettive devono seguire lo standard definito dal gruppo RPA/DevOps.
5. Differenza tra esecuzione locale e ambiente remoto
5.1 Esecuzione locale
In locale è presente l’intero repository.
Lo sviluppatore può quindi:
eseguire il codice direttamente sulla macchina;
modificare il codice;
buildare l’immagine;
eseguire il servizio tramite Compose local;
montare cartelle locali;
fare debug completo.
In locale il servizio può essere testato in tre modalità:
esecuzione a crudo sulla macchina;
esecuzione Dockerizzata con Compose local;
esecuzione Dockerizzata con Compose di ambiente, ad esempio dev.
5.2 Esecuzione su ambiente remoto
Nell’ambiente remoto non viene copiato l’intero repository.
Il servizio viene eseguito usando:
Docker Compose dell’ambiente;
file .env dell’ambiente;
immagine Docker pubblicata sul GitLab Container Registry;
eventuali file esterni non inclusi nell’immagine.
Questo significa che il servizio remoto deve essere autosufficiente a partire da immagine, Compose e configurazione.
6. Ambienti di rilascio
Idealmente i rilasci seguono tre ambienti:
sviluppo;
collaudo;
produzione.
6.1 Sviluppo
Ambiente usato per verificare il comportamento del servizio in un contesto remoto non produttivo.
Serve per validare:
immagine Docker;
Docker Compose;
configurazione .env;
connessioni verso sistemi esterni;
comportamento generale del servizio.
6.2 Collaudo
Ambiente usato per test più vicini alla produzione.
Serve per validare:
stabilità;
dati e configurazioni più rappresentativi;
integrazioni;
test utente o test funzionali finali.
6.3 Produzione
Ambiente finale in cui il servizio viene eseguito per l’utilizzo operativo.
Richiede maggiore attenzione su:
credenziali;
DNS;
configurazioni definitive;
disponibilità della VM;
tracciabilità;
impatto sugli utenti;
rollback.
6.4 Salto degli ambienti
In base a urgenza, criticità o caratteristiche dello sviluppo, alcuni step possono essere saltati.
Esempi:
rilascio diretto in collaudo;
rilascio diretto in produzione;
aggiornamento rapido di una fix urgente.
Il salto di uno o più ambienti deve essere consapevole e motivato, perché riduce il livello di verifica progressiva.
7. Fase preliminare: validazione locale
Prima di aprire un ticket di rilascio, lo sviluppatore deve verificare che il servizio funzioni correttamente in locale.
7.1 Test del servizio a crudo
Il primo test consiste nell’eseguire il servizio direttamente sulla macchina locale.
Obiettivo:
verificare che il codice Python funzioni;
verificare dipendenze;
verificare configurazioni base;
intercettare errori applicativi prima della containerizzazione.
Esempio:
python -m src.main
Oppure, in base alla struttura del progetto:
python src/main.py
7.2 Test con Compose local
Il secondo test consiste nell’eseguire il servizio tramite Compose local.
Esempio:
docker compose -f docker-compose.local.yml up --build
Obiettivo:
verificare Dockerfile;
verificare build dell’immagine;
verificare mount locali;
verificare gestione env;
verificare porte e volumi;
verificare comportamento containerizzato.
7.3 Test con Compose di ambiente
Dopo il Compose local, è consigliato testare almeno il Compose dev.
Esempio:
docker compose -f docker-compose.dev.yml --env-file .env.dev up
Obiettivo:
verificare che l’immagine sia compatibile con il Compose remoto;
verificare che il servizio non dipenda da file presenti solo nel repository locale;
verificare che le variabili siano sufficienti;
simulare il più possibile il comportamento della macchina remota.
8. Checklist pre-rilascio
Prima di richiedere il rilascio, verificare che:
il codice sia contenuto nella cartella src/;
siano presenti i Compose local, dev, collaudo e prod;
i mount dei Compose partano dalla cartella corrente;
non siano presenti path assoluti locali;
il Dockerfile sia aggiornato;
l’immagine sia buildabile;
il servizio sia stato testato a crudo;
il servizio sia stato testato con Compose local;
il servizio sia stato testato almeno con Compose dev;
il file .env dell’ambiente sia stato preparato;
il file .env non sia committato nel repository;
il file .env sia stato salvato in Bitwarden;
l’immagine sia stata pubblicata sul registry GitLab;
il Compose punti all’immagine corretta;
siano presenti eventuali label CD richieste;
siano stati identificati eventuali file esterni da allegare;
sia stata individuata la VM di destinazione dal file Move to Prod;
siano stati individuati eventuali DNS necessari.
9. Build e pubblicazione dell’immagine Docker
L’immagine Docker può essere pubblicata in due modalità:
tramite CI GitLab;
manualmente dall’ambiente locale dello sviluppatore.
9.1 Build tramite CI
La modalità preferibile è la build automatica tramite pipeline CI.
La pipeline può essere triggerata da:
push su branch;
merge;
tag di versione;
commit specifico;
workflow manuale.
L’immagine dovrebbe essere taggata in modo chiaro.
Esempi:
dev-latest
coll-latest
prod-latest
v1.2.3
commit-<sha>
Una strategia consigliata è avere sia tag ambientali sia tag immutabili.
Esempio:
dev-latest
v1.2.3
commit-a1b2c3d
In questo modo:
dev-latest permette aggiornamenti rapidi;
v1.2.3 permette tracciabilità;
commit-<sha> permette audit tecnico.
9.2 Build manuale
In alternativa, l’immagine può essere buildata localmente e pushata manualmente.
Esempio indicativo:
docker build -t registry.gitlab.com/gruppo/progetto/nome-servizio:dev-latest .
docker push registry.gitlab.com/gruppo/progetto/nome-servizio:dev-latest
La build manuale deve essere usata con attenzione, perché è meno tracciabile rispetto a una pipeline CI.
10. Preparazione del file .env
Il file .env dell’ambiente deve essere derivato dal file locale o dal file .env.example.
Ogni ambiente deve avere variabili specifiche e indipendenti.
10.1 Variabili da rendere specifiche per ambiente
Devono essere diverse per ogni ambiente, quando applicabile:
password utenti;
password database;
secret key;
token API;
connection string;
credenziali di servizio;
endpoint;
nomi database;
bucket;
utenti applicativi;
chiavi di cifratura;
configurazioni di integrazione.
Esempio:
APP_ENV=dev
LOG_LEVEL=INFO
DB_HOST=db-dev.internal
DB_PORT=5432
DB_NAME=automazione_dev
DB_USER=automazione_dev_user
DB_PASSWORD=<password-dev>
SECRET_KEY=<secret-dev>
10.2 Salvataggio su Bitwarden
Al termine della preparazione, il file .env deve essere salvato in Bitwarden nella raccolta RPA.
Naming convention:
env_<ambiente>_<nome_automazione>
Esempi:
env_dev_recupero-pratiche
env_coll_recupero-pratiche
env_prod_recupero-pratiche
Questo permette a chiunque sia autorizzato di:
recuperare l’environment;
eseguire debug locali;
verificare configurazioni;
recuperare credenziali di connessione;
aggiornare il servizio in modo controllato.
10.3 Creazione del Bitwarden Send
Dopo aver salvato il file .env, è necessario creare un Bitwarden Send.
Il Send può contenere:
il contenuto testuale del file .env;
oppure direttamente il file .env.
Il link del Send dovrà essere allegato al ticket DevOps.
11. Apertura del ticket di delivery microservizio
Per richiedere un nuovo rilascio, aprire un ticket nel sistema DevOps.
11.1 Tipologia ticket
La tipologia da selezionare è:
Delivery microservizio
Il ticket deve essere contestualizzato nell’ambiente RPA.
11.2 Ambiente remoto
Nel ticket deve essere specificato l’ambiente di rilascio:
sviluppo;
collaudo;
produzione.
Deve inoltre essere indicata la destinazione:
cloud;
quartier generale;
VM dedicata.
La VM deve essere scelta in base alla disponibilità riportata nel file Move to Prod, condiviso nel canale Teams del gruppo Python.
11.3 Informazioni da inserire nel ticket
Il ticket deve contenere almeno:
nome del servizio;
repository GitLab;
ambiente target;
VM target;
Docker Compose da utilizzare;
immagine Docker da utilizzare;
tag immagine;
link Bitwarden Send del file .env;
eventuali DNS richiesti;
eventuali file allegati da rilasciare;
eventuali cartelle di destinazione dei file;
eventuali note operative;
eventuali dipendenze o prerequisiti.
11.4 File da allegare o linkare
Al ticket devono essere allegati o referenziati:
Docker Compose relativo all’ambiente;
Bitwarden Send del file .env;
eventuali Excel di supporto;
eventuali shape file;
eventuali file dati;
eventuali template;
eventuali configurazioni non incluse nell’immagine.
I file che non risiedono nell’immagine Docker devono essere esplicitamente indicati, insieme al path in cui DevOps dovrà posizionarli.
Esempio:
Allegare il file input_template.xlsx nella cartella ./data/templates/
Allegare gli shapefile nella cartella ./data/shapes/
12. DNS e pubblicazione esterna
Se il servizio richiede pubblicazione esterna, nel ticket devono essere indicati i DNS necessari.
Come best practice, i DNS devono risiedere sotto i domini standard del gruppo.
Per sviluppo e collaudo:
.rpa.collaudo-live.xyz
Per produzione:
.rpa.eagleprojects.cloud
Esempi indicativi:
nome-servizio.rpa.collaudo-live.xyz
nome-servizio.rpa.eagleprojects.cloud
La naming convention effettiva deve essere coerente con gli standard del gruppo e approvata da DevOps.
13. Completamento del rilascio
Una volta che DevOps ha completato la lavorazione del ticket, lo sviluppatore deve verificare il servizio.
13.1 Verifiche post-rilascio
Verificare che:
il container sia avviato;
il servizio risponda correttamente;
i log non presentino errori critici;
le variabili ambiente siano corrette;
eventuali file allegati siano presenti;
eventuali DNS siano funzionanti;
eventuali integrazioni siano operative;
eventuali scheduler o job siano attivi;
eventuali endpoint siano raggiungibili.
13.2 Aggiornamento del file Move to Prod
A rilascio completato, aggiornare il file Move to Prod nelle colonne previste.
Inserire almeno:
nome servizio;
ambiente;
VM utilizzata;
DNS utilizzato;
repository;
eventuali note;
data rilascio;
riferimento ticket DevOps.
Il rilascio è considerato concluso solo dopo:
completamento ticket DevOps;
verifica tecnica del servizio;
aggiornamento del file Move to Prod.
14. Aggiornamento dei servizi esistenti
Gli aggiornamenti possono riguardare:
immagine Docker;
file .env;
Docker Compose;
file locali;
DNS;
configurazioni accessorie.
14.1 Aggiornamento immagine Docker
Se il servizio è stato configurato con le corrette label di Continuous Delivery, l’aggiornamento dell’immagine può avvenire automaticamente.
In questo caso è sufficiente pubblicare il nuovo tag latest relativo all’ambiente.
Esempi:
dev-latest
coll-latest
prod-latest
Il sistema di CD rileverà la nuova immagine e aggiornerà il servizio secondo la configurazione prevista.
14.2 Aggiornamento tramite CI
Modalità consigliata:
modificare il codice;
committare;
pushare su GitLab;
attendere build della pipeline;
verificare pubblicazione immagine;
verificare aggiornamento automatico del servizio;
controllare log e comportamento applicativo.
14.3 Aggiornamento manuale immagine
In caso di build manuale:
docker build -t registry.gitlab.com/gruppo/progetto/nome-servizio:dev-latest .
docker push registry.gitlab.com/gruppo/progetto/nome-servizio:dev-latest
Dopo il push, verificare che il sistema remoto abbia recepito l’aggiornamento.
15. Aggiornamento di .env, Compose o file locali
Gli aggiornamenti che non riguardano solamente l’immagine Docker devono passare tramite ticket DevOps.
15.1 Tipologia ticket
La tipologia da usare è:
Aggiornamento microservizio
15.2 Informazioni richieste
Nel ticket specificare:
servizio da aggiornare;
ambiente interessato;
VM interessata;
modifica richiesta;
nuovo file .env, se necessario;
link Bitwarden Send aggiornato;
nuovo Docker Compose, se necessario;
file da inserire o sostituire;
path di destinazione;
eventuali istruzioni di riavvio;
eventuali verifiche da eseguire.
15.3 Aggiornamento del file .env
Se cambia il file .env:
aggiornare il contenuto;
salvare la nuova versione in Bitwarden;
creare un nuovo Bitwarden Send;
allegare il Send al ticket;
indicare chiaramente che il servizio deve essere riavviato, se necessario.
15.4 Aggiornamento del Compose
Se cambia il Docker Compose:
testare il Compose localmente;
verificare che l’immagine esista sul registry;
allegare il nuovo Compose al ticket;
descrivere le modifiche principali;
specificare eventuali impatti su volumi, porte, label o reti.
15.5 Aggiornamento di file locali
Se devono essere aggiunti o modificati file locali:
allegare i file al ticket;
indicare il path di destinazione;
specificare se sostituiscono file esistenti;
indicare se è necessario riavviare il servizio.
Esempio:
Sostituire il file configurazione.xlsx nella cartella ./data/config/
Aggiungere la cartella ./data/shapes/ con il contenuto allegato
Riavviare il servizio al termine della copia
16. Template ticket Delivery microservizio
Titolo:
[DELIVERY MICROSERVIZIO] <nome-servizio> - <ambiente>
Descrizione:
Richiedo il rilascio del servizio RPA <nome-servizio> sull’ambiente <dev/collaudo/prod>.
Repository GitLab:
<link repository>
Ambiente:
<dev/collaudo/prod>
Destinazione:
<cloud/quartier generale/VM dedicata>
VM target:
<nome VM>
Immagine Docker:
<registry/image:tag>
Docker Compose:
<allegato o link>
File .env:
<link Bitwarden Send>
DNS richiesti:
<dns richiesti oppure N/A>
File aggiuntivi:
<elenco file, path di destinazione, eventuali note>
Note operative:
<eventuali istruzioni specifiche>
Verifiche richieste:
- avvio container
- verifica log
- verifica endpoint/scheduler/job
- verifica DNS, se presente
17. Template ticket Aggiornamento microservizio
Titolo:
[AGGIORNAMENTO MICROSERVIZIO] <nome-servizio> - <ambiente>
Descrizione:
Richiedo l’aggiornamento del servizio RPA <nome-servizio> sull’ambiente <dev/collaudo/prod>.
Servizio:
<nome-servizio>
Ambiente:
<dev/collaudo/prod>
VM:
<nome VM>
Tipo aggiornamento:
- immagine Docker
- file .env
- Docker Compose
- file locali
- DNS
- altro
Dettaglio modifica:
<descrizione dettagliata della modifica>
Nuova immagine Docker:
<registry/image:tag oppure N/A>
Nuovo file .env:
<link Bitwarden Send oppure N/A>
Nuovo Docker Compose:
<allegato/link oppure N/A>
File da aggiungere/sostituire:
<elenco file e path di destinazione oppure N/A>
Riavvio richiesto:
<sì/no>
Note operative:
<eventuali dettagli aggiuntivi>
18. Checklist finale rilascio
Prima di considerare concluso il rilascio, verificare:
ticket DevOps completato;
servizio avviato;
log verificati;
DNS funzionante, se previsto;
credenziali salvate correttamente in Bitwarden;
file .env non presente nel repository;
Compose corretto sull’ambiente;
immagine corretta in esecuzione;
file esterni presenti;
Move to Prod aggiornato;
eventuali stakeholder informati.
19. Regole pratiche da ricordare
19.1 Non rilasciare codice non testato
Prima del rilascio, il servizio deve essere stato testato almeno:
a crudo;
con Compose local;
con Compose dev o Compose equivalente all’ambiente remoto.
19.2 Non committare file .env
I file .env reali non devono essere salvati nel repository.
Nel repository deve essere presente solo un file di esempio, come:
.env.example
19.3 Non usare path assoluti locali nei Compose
I mount devono partire dalla cartella corrente:
./data:/app/data
E non da path assoluti della macchina dello sviluppatore:
/home/nomeutente/progetto/data:/app/data
19.4 Non dipendere dal repository completo in remoto
In ambiente remoto il servizio deve funzionare con:
immagine Docker;
Docker Compose;
file .env;
file esterni dichiarati.
19.5 Aggiornare sempre Move to Prod
Il file Move to Prod è necessario per mantenere tracciabilità operativa dei servizi rilasciati.
Ogni rilascio o variazione significativa deve essere riportata nel file.
20. Flusso sintetico
Nuovo rilascio
Sviluppo codice
↓
Validazione repository
↓
Test a crudo
↓
Test Compose local
↓
Test Compose dev/coll/prod
↓
Build immagine
↓
Push immagine su GitLab Registry
↓
Preparazione file .env ambiente
↓
Salvataggio .env su Bitwarden
↓
Creazione Bitwarden Send
↓
Scelta VM da Move to Prod
↓
Apertura ticket Delivery microservizio
↓
Lavorazione DevOps
↓
Verifica servizio
↓
Aggiornamento Move to Prod
↓
Rilascio concluso
Aggiornamento servizio
Modifica codice/configurazione
↓
Test locale
↓
Se cambia solo immagine:
push nuovo tag latest ambiente
verifica aggiornamento automatico CD
↓
Se cambiano env/compose/file:
aggiornamento Bitwarden se necessario
apertura ticket Aggiornamento microservizio
lavorazione DevOps
↓
Verifica servizio
↓
Aggiornamento Move to Prod se necessario