devops-deployer

Sebyone S.r.l. — https://sebyone.it · proprietary, © 2026 Sebyone S.r.l. Version 3.6.2 · Author: Paolo Lo Giacco p.logiacco@sebyone.it

Strumento di deploy parametrico per gli ambienti di test, stage e locale: un solo script bash pubblica molti progetti, prendendo il codice dalla loro repository GitHub di sviluppo. Ogni progetto è un file di configurazione, e l'estensione decide il runtime:

Config	Modalità	Runtime
.deps/<progetto>.dep	bare	app sul server (nginx + PHP-FPM / systemd)
.deps/<progetto>.ddep	docker	app in container (Docker Compose)

⚠️ Non per la produzione

Pubblica con fetch + reset --hard su un ramo: porta sull'ambiente lo stato corrente del ramo, non un artefatto versionato e riproducibile. È quello che serve per provare in fretta un branch su un ambiente di prova.

La produzione si installa dai pacchetti di rilascio: una build produce un artefatto versionato, è quello a essere testato e approvato, e sono gli stessi byte a finire su ogni macchina.

---

Installare

sudo mkdir -p /opt/deployer/.deps
cd /opt/deployer
sudo wget -O deployer.sh \
  https://raw.githubusercontent.com/sebyone/devops-deployer/main/linux/debian/deployer.sh
sudo chmod +x deployer.sh
./deployer.sh --version

Nel repository lo script sta in linux/debian/: il percorso dichiara la piattaforma. Sul server non si replica — deployer.sh va in /opt/deployer con .deps/ accanto. Dettagli, prerequisiti per stack e aggiornamento: INSTALL.md.

Configurare un progetto

La via rapida è --new: chiede nome, modalità, repository, ramo, chiave SSH, percorso di destinazione, stack e owner, poi scrive uno scheletro commentato (mode 600). Non sovrascrive mai una config esistente.

cd /opt/deployer
sudo ./deployer.sh --new

In alternativa, partendo dai template:

cd /opt/deployer/.deps

# scarica i template una volta sola
sudo wget -O example.dep \
  https://raw.githubusercontent.com/sebyone/devops-deployer/main/linux/debian/.deps/example.dep
sudo wget -O example.ddep \
  https://raw.githubusercontent.com/sebyone/devops-deployer/main/linux/debian/.deps/example.ddep

sudo cp example.dep progetto.dep      # bare    → .dep
# sudo cp example.ddep progetto.ddep  # docker  → .ddep

sudo nano progetto.dep                # REPO_SSH_URL, TARGET_PATH, STACK, POST_INSTALL…
sudo chmod 600 progetto.dep           # è codice privilegiato: eseguito come root

Campi minimi — bare: REPO_SSH_URL, TARGET_PATH, STACK. docker: PROJECT_ROOT (assoluto), SERVICE, un COMPOSE_FILE esistente.

In modalità bare STACK sceglie il profilo del progetto: riempie i passi e le cartelle scrivibili di default, che la config può sempre sovrascrivere.

Il progetto è…	STACK	composer	nginx	scrivibili
app Laravel su nginx + PHP-FPM	php-laravel	sì	sì	storage bootstrap/cache
PHP generico su nginx + PHP-FPM	php-nginx	sì	sì	storage vendor
sito statico	static-nginx	no	sì	(nessuna)
SvelteKit + Spring Boot dietro proxy	node-spring-nginx	no	sì	(nessuna)
servizio Python con unit systemd	python-nginx	no¹	sì	(nessuna)
nessuna delle precedenti	none	no	no	(nessuna)

¹ python-nginx non usa composer ma crea il virtualenv e installa i requirements.txt (DO_VENV, VENV_PATH, VENV_REQUIREMENTS).

Uno STACK non previsto è un errore fatale, non un default silenzioso. Dettagli di ogni profilo, prerequisiti e come sovrascrivere i default: Parte I della guida.

.deps inizia con un punto: ls non la mostra, serve ls -a.

Prima pubblicazione

Ogni passo verifica il precedente:

cd /opt/deployer

./deployer.sh --list                      # lo strumento vede la config?
sudo ./deployer.sh progetto --dry-run     # valida config e pre-flight, non cambia nulla
sudo ./deployer.sh progetto --init        # primo checkout: clona e si ferma
# → predisponi vhost nginx / unit systemd / .env
sudo ./deployer.sh progetto --no-db       # primo deploy, database intatto
sudo ./deployer.sh progetto               # deploy completo

Il --no-db separato distingue «il codice non si costruisce / i permessi sono sbagliati» da «la migrazione fallisce».

Una config può dichiarare due campi facoltativi:

MIN_DEPLOYER_VERSION="3.6.0"   # versione minima dello script che le serve
CONF_REVISION="3"              # revisione di questo file, registrata nello storico

---

Comandi

Ogni comando con un esempio d'uso. <progetto> è il nome base della config in .deps/.

Pubblicare

sudo ./deployer.sh shareforces                 # deploy completo
sudo ./deployer.sh shareforces --no-db         # solo codice: salta i comandi 'db:'
sudo ./deployer.sh shareforces --db:seed       # dei 'db:', esegue solo il set "seed"
sudo ./deployer.sh shareforces --dry-run       # stampa i passi, non cambia nulla
sudo ./deployer.sh shareforces --no-git        # pubblica il codice già su disco
sudo ./deployer.sh shareforces --bare          # forza .dep se esiste anche .ddep

I set db: con label sono opt-in: senza --db: gira solo default. Un seed non parte a ogni deploy solo perché è dichiarato nella config.

In modalità docker (.ddep):

sudo ./deployer.sh altroprogetto               # build + up + POST_UP
sudo ./deployer.sh altroprogetto --no-build    # riavvia senza ricostruire l'immagine
sudo ./deployer.sh altroprogetto --docker      # forza .ddep se esiste anche .dep

Preparare il codice, senza pubblicare

sudo ./deployer.sh shareforces --init          # primo checkout: clona e si ferma
sudo ./deployer.sh shareforces --checkout      # aggiorna l'albero alla punta di BRANCH
sudo ./deployer.sh shareforces --env-refresh   # ricostruisce gli .env dagli example

Nessuno dei tre esegue build, migrazioni o reload, e nessuno viene registrato nello storico. --init clona solo se l'albero manca; --checkout aggiorna anche quello esistente.

--env-refresh ricostruisce ogni .env del checkout con la struttura del suo .env.example e i valori di quello esistente. Le chiavi non più previste vengono scartate, ma restano nel backup datato.

Tornare indietro

./deployer.sh shareforces --history            # i deploy registrati
sudo ./deployer.sh shareforces --rollback      # torna al deploy precedente
sudo ./deployer.sh shareforces --no-rollback   # su errore NON ripristina da solo

Configurazioni

sudo ./deployer.sh --new                       # crea una config da zero (interattivo)
sudo ./deployer.sh shareforces --import        # importa quella versionata nel progetto
sudo ./deployer.sh --import-all /opt/www/mono  # tutte quelle che una repo espone
./deployer.sh --list                           # i progetti configurati
./deployer.sh shareforces --list-db            # i set 'db:' dichiarati dalla config

L'import prende dal progetto i passi del deploy (STACK, POST_INSTALL, VERIFY, CONF_REVISION) e conserva ciò che descrive questa macchina: TARGET_PATH, TARGET_USER/GROUP, REPO_SSH_KEY, NGINX_VHOST, SITE_URL (in docker: PROJECT_ROOT, ENV_FILE, DOCKER_NETWORK). La copia nel progetto resta intatta.

Prima di sovrascrivere salva un backup con timestamp (progetto.dep.2026-10-31T09-14-22.bak) che si accumula, più un .bak semplice che punta all'ultima versione. --import-all non pubblica: le config arrivano, poi decidi tu cosa pubblicare.

Lo strumento

cd /opt/deployer && sudo ./deployer.sh --update  # aggiorna, poi verifica le config
./deployer.sh --check                          # verifica le config, senza aggiornare
./deployer.sh --help                            # riferimento completo
./deployer.sh --version                         # stampa la versione

---

Riferimento

Comandi

Comando	Effetto
<progetto>	Pubblica il progetto
<progetto> --init	Primo checkout: clona la repo e si ferma, senza eseguire nulla
<progetto> --checkout	Aggiorna il codice e basta: porta l'albero alla punta di BRANCH
<progetto> --env-refresh	Ricostruisce gli .env dai rispettivi example, conservando i valori in uso
<progetto> --rollback	Ripubblica il commit del deploy precedente
<progetto> --history	Deploy registrati e target di --rollback
<progetto> --list-db	Elenca i set db: dichiarati dalla config
<progetto> --import	Importa la config versionata nel progetto, conservando i valori di questa macchina
--new	Crea una configurazione da zero, interattivo
--import-all <checkout>	Importa tutte le config che una repo espone (monorepo)
--list	Progetti configurati, con la loro modalità
--update	Aggiorna lo script, poi verifica le config
--check	Verifica le config contro la versione installata
--help, -h	Riferimento completo
--version, -v	Stampa la versione

Opzioni di deploy

Si combinano e stanno in qualunque posizione.

Opzione	Modalità	Effetto
--bare / --docker	entrambe	Forza .dep / .ddep: serve se esistono entrambi per lo stesso nome
--no-db	entrambe	Solo codice: salta i comandi marcati db: (migrazioni, seed)
--db:<label>	entrambe	Esegue solo i set db: indicati; ripetibile. Senza questa flag gira solo il set default: i set con label sono opt-in
--no-git	entrambe	Pubblica il codice già su disco, senza fetch
--no-rollback	entrambe	In caso di errore lascia l'albero alla versione fallita
--dry-run	entrambe	Stampa i passi senza cambiare nulla
--no-build	docker	Riavvia i container senza ricostruire l'immagine

Se un progetto ha sia <nome>.dep sia <nome>.ddep la modalità è ambigua: lo strumento si ferma finché non scegli con --bare o --docker.

--rollback ripristina solo il codice: le migrazioni non si annullano rieseguendole, vanno dichiarate in ROLLBACK_CMDS. Un secondo --rollback va un passo più indietro, non torna al commit difettoso.

Uscita e ambiente

Codice	Significato
0	Operazione riuscita
1	Errore: passo fallito, opzione sconosciuta, config non trovata o ambigua
2	Invocazione senza progetto (stampa l'uso breve)

Variabile	Default	Significato
DEPLOYER_CONF_DIR	<script-dir>/.deps	Cartella delle configurazioni
DEPLOYER_STATE_DIR	<script-dir>/.state	Storico dei deploy (serve a --rollback)
DEPLOYER_UPDATE_URL	…/main/linux/debian/deployer.sh	Sorgente di --update, es. un URL con token

---

Strumento vs progetto

Lo strumento è generico: non contiene logica di un progetto specifico.

devops-deployer/
├── linux/debian/          lo strumento per Debian (la piattaforma è nel percorso)
│   ├── deployer.sh        lo script (unica versione, entrambe le modalità)
│   └── .deps/             le configurazioni (nascosta: serve `ls -a`)
│       ├── example.dep    template bare
│       └── example.ddep   template docker
├── docs/DEPLOYER.md       la guida: lo strumento + onboarding di un progetto
├── docs/tools-specs.md    sviluppare i tool postdeploy / testenv
├── INSTALL.md             installazione su Linux
├── CHANGELOG.md           storico delle versioni
├── AI-facing.md           istruzioni per agenti AI
└── README.md

Ogni progetto fornisce, nel proprio repository: la configurazione (<progetto>.dep/.ddep), i tool richiamati dalla config (tipicamente tools/postdeploy.sh e tools/testenv.php), e i vhost nginx (bare) o Dockerfile/docker-compose.yml (docker).

Regola pratica: se un file sa cos'è il progetto → sta nel repo del progetto. Se è la meccanica del deploy uguale per tutti → sta qui.

---

Far adeguare un progetto da un agente AI

AI-facing.md è il contratto in forma operativa: struttura da creare, modelli di configurazione, le sei regole che i tool devono rispettare e una checklist verificabile. È scritto per essere dato a un agente, non letto da una persona.

Primo passo: mettiglielo in mano. Il repository è privato, quindi l'agente non può scaricarlo da solo: copia il file nel repo del progetto, oppure incollane il contenuto nel prompt.

# dal repo del progetto da adeguare
curl -fsSL -o AI-facing.md \
  https://raw.githubusercontent.com/sebyone/devops-deployer/main/AI-facing.md

Prompt per il primo adeguamento

Sostituisci <progetto> e l'URL della repo. Il resto è deliberato: chiede un'analisi prima delle modifiche, e la checklist come criterio di completamento.

Leggi AI-facing.md: è il contratto dello strumento di deploy `deployer.sh`
che pubblicherà questo progetto su un ambiente di test.

Adegua QUESTO repository a quel contratto.

1. Prima analizza il progetto e dimmi cosa hai dedotto, senza modificare nulla:
   modalità (bare o docker), STACK, se serve una build, se c'è uno schema DB,
   cosa scrive l'app a runtime. Motiva ogni deduzione con i file che l'hanno
   suggerita.
2. Aspetta la mia conferma.
3. Poi crea la struttura e i file: la configurazione in
   tools/devops/.deps/<progetto>.dep (o .ddep), il tool postdeploy e il
   self-test testenv, seguendo le sei regole della sezione 4.
4. Chiudi verificando la checklist della sezione 7, voce per voce, e dimmi
   quali punti non puoi soddisfare e perché.

Dati del progetto:
- nome: <progetto>
- repo: git@github.com:<org>/<progetto>.git
- ambiente di destinazione: test

Perché il passo 2. Le deduzioni della sezione 1 (modalità, STACK) decidono tutto il resto: correggerle dopo significa rifare il lavoro. Se sbaglia lì, il resto sarà coerentemente sbagliato.

Prompt per una revisione

Quando il progetto è già adeguato e vuoi solo un controllo:

Leggi AI-facing.md. Verifica questo repository contro la checklist della
sezione 7, voce per voce, senza modificare nulla. Per ogni voce rispondi
OK / NON CONFORME / NON APPLICABILE, e per le non conformi indica il file,
la riga e la correzione minima.

Prompt per un adeguamento parziale

Leggi AI-facing.md, sezione 4 (contratto dei tool) e sezione 5 (idempotenza).
Rivedi tools/postdeploy.sh: deve uscire non-zero sui fallimenti, propagare
l'exit code dei processi figli e usare percorsi relativi alla root.
Non toccare altro.

Cosa verificare tu, dopo

L'agente non ha accesso al server: la prova finale resta manuale.

/opt/deployer/deployer.sh <progetto> --list-db   # i set db: sono quelli attesi
sudo /opt/deployer/deployer.sh <progetto> --dry-run
sudo /opt/deployer/deployer.sh <progetto> --init
sudo /opt/deployer/deployer.sh <progetto> --no-db

Tre cose che l'agente non deve fare, e che AI-facing.md gli dice esplicitamente: copiare deployer.sh dentro il progetto quando esiste già un'installazione centralizzata, inventare parametri di configurazione, far scrivere al deploy i vhost nginx o le unit systemd. Se le vedi nel risultato, il file non è stato letto.

---

Documentazione

• INSTALL.md — installare, configurare, aggiornare, disinstallare.
• docs/DEPLOYER.md — la guida in due parti: lo strumento (parametri, STACK, prerequisiti, troubleshooting) e rendere compatibile un progetto (struttura, tool postdeploy/testenv, il contratto che devono rispettare).
• docs/tools-specs.md — manuale per sviluppare i tool postdeploy e testenv: forma, helper, sottocomandi e le specificità di ogni STACK.
• CHANGELOG.md — storico delle versioni e note di migrazione.
• AI-facing.md — istruzioni per agenti AI che devono rendere un progetto conforme al contratto: struttura, config, tool, checklist verificabile.
• ./deployer.sh --help — sempre allineato alla versione installata.