Guida pratica: Ansible + Code-Server + Semaphore UI (Ansvil Project)

Prerequisiti

Installazione di make, git e docker

Debian/Ubuntu

1. Aggiorna i pacchetti di sistema

sudo apt update

2. Installa strumenti di base

sudo apt install -y make git curl gnupg ca-certificates lsb-release

3. Rimuovi Docker preinstallato (se presente)

sudo apt remove -y docker docker-engine docker.io containerd runc

4. Aggiungi la chiave GPG ufficiale di Docker

curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | \
sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

5. Aggiungi il repository Docker ufficiale

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") $(lsb_release -cs) stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

6. Installa Docker

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

7. Abilita e avvia il servizio Docker

sudo systemctl enable --now docker

8. Apri le porte web 80/443 nel firewall (facoltativo)

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload

RHEL / CentOS / Fedora / AlmaLinux

1. Installa strumenti di base

sudo dnf install -y make git dnf-plugins-core

2. Rimuovi Docker preinstallato (se presente)

sudo dnf remove -y docker docker-client docker-client-latest docker-common docker-latest \
docker-latest-logrotate docker-logrotate docker-engine podman

3. Aggiungi il repository Docker ufficiale

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

4. Installa Docker

sudo dnf install -y docker-ce docker-ce-cli containerd.io

5. Abilita e avvia il servizio Docker

sudo systemctl enable --now docker

6. Apri le porte web 80/443 nel firewall (facoltativo)

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

Installazione di ANSVIL

1. Clona il repository

Clona il progetto ANSVIL da GitHub e accedi alla directory:

git clone https://github.com/lineadicomando/ansvil.git
cd ansvil

2. Avvia l’ambiente tramite make

Inizializzazione

make init

• Genera il file .env con le variabili d’ambiente richieste
• Ti chiederà le password iniziali da impostare per:
  • Code-Server
  • Semaphore UI
• Tutti gli altri parametri (es. porte, volumi, path) vanno modificati manualmente nel file .env dopo la creazione

Avvio dei servizi

Per avviare tutti i container in background:

make up

Questo comando esegue docker-compose con tutti i servizi ANSVIL attivi:
Code-Server, Semaphore, PostgreSQL, proxy, ecc.

Primo avvio: attendi qualche istante

Attenzione: al primo avvio, il sistema impiega alcuni secondi/minuti per:

• generare file di configurazione
• inizializzare il database di Semaphore
• creare certificati SSL self-signed

Durante questa fase, se visiti subito https://localhost, potresti vedere errori o pagine vuote.
Aspetta 10–30 secondi, poi ricarica il browser.

Puoi monitorare lo stato dei container con:

make ps
make logs

Altri comandi utili (make help)

Per visualizzare l’elenco completo dei comandi disponibili:

make help

Output:

Available commands:
[...]
ps                Show the status of Docker Compose services
status            Alias for ps
up                Start Docker Compose services in background
down              Stop and remove Docker Compose services
start             Start existing Docker Compose containers
stop              Stop running Docker Compose containers without removing them
restart           Restart Docker Compose services (full rebuild)
restart-soft      Restart services without recreating containers
logs              Show logs from all services
[...]

Comandi principali

Nota: I comandi start, stop e restart-soft non rileggono le variabili d’ambiente.

Comportamento dei container con restart: unless-stopped

Tutti i servizi ANSVIL usano la direttiva Docker:

 restart: unless-stopped

Questo significa:

• I container verranno riavviati automaticamente dopo un reboot del sistema o un crash del demone Docker
• Se fermati manualmente con make stop, non verranno riavviati automaticamente al reboot
• Se invece usi make down (che rimuove i container), al prossimo make up verranno ricreati da zero

Accesso ai servizi

Apri il browser e visita:

https://127.0.0.1

Oppure, dalla rete locale (se il firewall lo consente):

https://ansvil.local     # se configurato in DNS o in /etc/hosts
https://<IP-locale>      # es. https://192.168.1.42

Credenziali di default

Puoi modificare le credenziali predefinite nel file .env generato da make init.
Attenzione, dopo il primo avvio la modifica delle credenziali non ha effetto: fare riferimento alla documentazione di Code-Server e Semaphore UI

Considerazioni di sicurezza

• Tutti i servizi ANSVIL sono eseguiti con network_mode: host, quindi le porte dei container sono direttamente esposte sull’host.
  • Non c’è isolamento tra container e host a livello di rete.
  • Qualsiasi porta usata da ANSVIL deve essere libera sull’host al momento dell’avvio.
• Non devono essere attivi altri servizi sull’host che usano le stesse porte (es. Nginx, Apache, MySQL locali), altrimenti i container ANSVIL falliranno l’avvio per conflitto di porte.
• Si consiglia vivamente di dedicare una macchina (fisica o virtuale) esclusiva ad ANSVIL, per evitare conflitti e garantire stabilità, sicurezza e prevedibilità dell’ambiente.

Rete e firewall

• Esporre solo le porte strettamente necessarie (tipicamente 80 e 443 per accesso web).
• Tutte le altre porte (es. 8080, 3000, 3306) sono utilizzate da servizi interni e devono restare chiuse verso l’esterno.
• Firewall obbligatorio: configura regole esplicite per le sole porte autorizzate, bloccando il resto.

Sincronizzazione oraria

• Raccomandata una sincronizzazione NTP affidabile:
  • Evita problemi con certificati TLS, token di autenticazione e log distribuiti.
  • Puoi usare chrony o systemd-timesyncd, a seconda della distribuzione.

Persistenza dei dati

ANSVIL conserva tutti i dati importanti in due directory locali mappate nel progetto:

• ./projects/ → Workspace utente di Code-Server
• ./data/ → Dati di tutti gli altri servizi:
  • Database MariaDB di Semaphore
  • Script personalizzati (bashrc.d/, entrypoint.d/)
  • Certificati SSL e configurazioni interne

Sicurezza e conservazione

• I dati sono salvati sul filesystem locale, non in volumi Docker interni.
• Restano intatti durante:
  • Riavvii del sistema o dei container
  • Aggiornamenti della configurazione o dei servizi
  • Esecuzione dei comandi make up, make down, make restart

Puoi eseguire un backup completo copiando semplicemente le directory data/ e projects/, dopo aver fermato i servizi.

Hook di inizializzazione: personalizzazioni persistenti

ANSVIL supporta hook modulari che vengono eseguiti in momenti chiave del ciclo di vita dei container.
Questi script consentono di installare moduli Ansible, librerie Python, eseguire check personalizzati, operazioni di cleanup e altro.

Struttura delle directory

Gli script devono essere posizionati in:

./data/entrypoint.d/
├── root/     # eseguiti come root
└── user/     # eseguiti come utente ansvil

Eventi disponibili

Convenzione di naming

Gli script devono seguire il formato:

NN-<evento>-<descrizione>.sh

Esempi validi:

10-init-install-ansible.sh
20-start-healthcheck.sh
99-exit-cleanup.sh

• Gli script vengono eseguiti in ordine numerico crescente, separatamente per root/ e user/.
• Devono essere eseguibili (chmod +x).

Esempio pratico: installazione moduli Ansible

1. Crea uno script nella cartella user/:

nano ./data/entrypoint.d/user/10-init-install-extra.sh

2. Contenuto dello script:

#!/bin/bash
echo ">> [user/init] Installazione pacchetti custom"

ansible-galaxy collection install oxivanisher.linux_desktop
pip install netaddr passlib

3. Rendi eseguibile lo script:

chmod +x ./data/entrypoint.d/user/10-init-install-extra.sh

Linkografia essenziale

• GitHub – lineadicomando/ansvil
• PyPI · The Python Package
• Ansible Galaxy Collections
• Documentazione ufficiale di Ansible
• YAML Syntax
• Jinja — Jinja Documentation
• Semaphore UI
• Code Server