Installare Ansible AWX su Debian 12 passo dopo passo

Installare AWX su Debian 12: scelta del metodo

Su Debian 12, il modo più lineare per mettere in piedi Ansible AWX è usare il deployment containerizzato con Docker e Docker Compose. È la strada meno fragile rispetto a un’installazione manuale dei componenti, perché AWX richiede più servizi coordinati: database, Redis, controller, web e task runner.

In pratica hai due strade: installazione tramite AWX Operator su Kubernetes oppure deployment con Docker Compose su una singola macchina. Se il requisito è una installazione rapida su Debian 12, senza cluster Kubernetes, il percorso con Compose è quello più diretto. Se invece vuoi alta disponibilità, scaling e lifecycle più robusto, l’Operator è la scelta corretta, ma richiede un’infrastruttura diversa.

Qui tratto il caso più comune: AWX su una VM o server Debian 12 standalone, con attenzione a prerequisiti, persistenza dati, reverse proxy e verifica finale.

Prerequisiti e dimensionamento minimo

Prima di partire, verifica che il server abbia risorse sufficienti. AWX non è leggero, soprattutto se usato da più utenti o con job frequenti.

• CPU: almeno 2 vCPU; meglio 4.
• RAM: minimo 4 GB; consigliati 8 GB o più.
• Disco: almeno 20 GB liberi, meglio se su volume separato per dati persistenti e log.
• Accesso root o sudo: necessario per installare pacchetti e configurare servizi.
• Rete: porta 80/443 se esponi AWX via reverse proxy; la porta interna dipende dal deployment.

Assumi inoltre che la macchina abbia un nome host corretto e che il DNS pubblico o interno punti al server, se devi pubblicare l’interfaccia web.

Aggiornare Debian 12 e preparare il sistema

Parti sempre da un sistema aggiornato. È un passaggio banale, ma evita molti problemi di dipendenze e librerie vecchie.

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg git lsb-release apt-transport-https

Controlla anche l’identità della macchina e la versione del kernel, utile per capire se il sistema è coerente con Debian 12:

cat /etc/debian_version
uname -a
hostnamectl

Se il server è dietro proxy aziendale o firewall restrittivo, verifica subito che possa raggiungere i repository e scaricare immagini container. AWX dipende da pull di immagini da registry pubblici o privati, quindi un blocco di rete si traduce in installazione fallita o servizi che non partono.

Installare Docker su Debian 12

Per AWX in modalità Compose, Docker è il motore più semplice da usare. Su Debian 12 conviene installarlo dal repository ufficiale Docker, non dai pacchetti generici della distro, per avere versioni aggiornate e compatibilità migliore con Compose.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

Verifica che il servizio sia attivo:

sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

Se vuoi usare Docker senza sudo per il tuo utente amministrativo, puoi aggiungerlo al gruppo docker. È comodo, ma va valutato con attenzione perché amplia i privilegi locali.

sudo usermod -aG docker $USER

Dopo questa modifica devi fare logout e login. Se stai operando in ambiente con forte controllo degli accessi, resta pure su sudo: è più pulito dal punto di vista di sicurezza.

Scaricare AWX e preparare il deployment

AWX pubblica un repository con i file di installazione. Per la modalità Docker Compose, il punto di partenza è il materiale di deployment incluso nel progetto. Prima di procedere, verifica la versione che vuoi usare: è meglio fissare una release stabile invece di inseguire sempre l’ultimo commit.

Clona il repository ufficiale e spostati nella directory corretta:

cd /opt
sudo git clone https://github.com/ansible/awx.git
cd awx

In molti casi conviene lavorare su una release taggata, non sul ramo principale. Il ramo principale può cambiare e introdurre differenze non previste. Se scegli una release, controlla i tag disponibili e fai checkout di quello desiderato.

git tag | tail
# esempio:
# git checkout 24.6.1

Il repository contiene materiale per più metodi di installazione. Per Docker Compose, cerca la directory dedicata al deployment. La struttura può cambiare tra versioni, quindi non dare per scontato un path fisso senza prima elencare i contenuti.

find . -maxdepth 3 -type f | grep -E 'compose|docker|install'

Configurare variabili e persistenza

AWX deve conservare dati e configurazione in modo persistente. I punti minimi da proteggere sono database, chiavi, media e configurazioni del controller.

Prima di avviare, individua il file di configurazione fornito dal deployment. In genere ci sono esempi o variabili da completare per hostname, password, porte e percorsi volume. L’obiettivo è definire almeno:

• nome host o FQDN con cui raggiungerai AWX;
• password del database e dell’admin iniziale;
• volumi persistenti per database e dati applicativi;
• eventuale reverse proxy se non esponi AWX direttamente;
• timezone corretta, utile per log e scheduling job.

Se il pacchetto di deployment prevede un file `.env` o un file YAML di configurazione, crea una copia di lavoro e non modificare l’originale senza backup.

cp .env .env.bak 2>/dev/null || true
cp inventory/hosts inventory/hosts.bak 2>/dev/null || true

Se il deployment usa Docker Compose con variabili, imposta valori robusti e non riutilizzare password deboli. Evita segreti in chiaro nei documenti condivisi; se devi documentare, redigi i valori sensibili.

Avviare AWX con Docker Compose

Quando il progetto è pronto, puoi avviare lo stack. Il comando esatto dipende dal percorso del file Compose, ma il flusso resta lo stesso: pull immagini, build eventuale, start dei servizi.

docker compose pull
docker compose up -d

Se il repository usa un file Compose dedicato, specifica il path corretto, ad esempio:

docker compose -f docker-compose.yml up -d

Controlla subito lo stato dei container:

docker ps
docker compose ps

Se uno o più container restano in restart loop, non andare avanti a tentativi ciechi. Leggi i log del servizio che fallisce, perché il problema tipico è quasi sempre uno di questi: variabili mancanti, database non pronto, permessi sui volumi, immagini non scaricabili o mismatch di versione.

docker compose logs --tail=200

Verificare il primo accesso web

Quando i container sono su, prova a raggiungere l’interfaccia web. Se AWX espone una porta locale, verifica con curl prima del browser:

curl -I http://127.0.0.1:PORTA

Sostituisci PORTA con quella configurata nel deployment. Se risponde con 200, 302 o comunque con header HTTP sensati, il layer applicativo sta rispondendo. Se invece ottieni timeout o connection refused, il problema è a livello di servizio o binding porta.

Al primo accesso, usa l’account admin creato in fase di bootstrap. Se il progetto prevede una password iniziale generata o letta da file, recuperala dal posto corretto, non inventarla. In alcuni setup la password è salvata in un file di output o in un secret del deployment.

Una volta dentro, controlla che la dashboard sia accessibile e che i menu principali rispondano: inventari, credenziali, job templates, execution environments. Se manca qualcosa, non è detto che l’installazione sia rotta; può essere solo un problema di bootstrap incompleto o di permessi.

Mettere AWX dietro reverse proxy

Su un server Debian 12 esposto in rete, è più pulito mettere AWX dietro Nginx o Apache con TLS. In questo modo separi la terminazione HTTPS dal servizio applicativo e puoi gestire certificati, redirect e header in modo standard.

Con Nginx, la logica è semplice: inoltri verso la porta locale di AWX, mantieni gli header corretti e abiliti WebSocket se richiesto dalla versione in uso. Se usi Apache, il concetto resta uguale con ProxyPass e ProxyPassReverse.

Esempio concettuale di reverse proxy Nginx:

server {
    listen 443 ssl;
    server_name awx.example.com;

    ssl_certificate     /etc/letsencrypt/live/awx.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/awx.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:PORTA;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Host $host;
    }
}

Dopo il reload del reverse proxy, verifica con:

curl -Ik https://awx.example.com

Atteso: risposta valida con certificato corretto e redirect o pagina login. Se ottieni errore 502, il proxy non raggiunge il backend; se ottieni 404, il virtual host non è agganciato correttamente.

Risoluzione dei problemi più comuni

Se AWX non parte, i casi ricorrenti sono pochi e riconoscibili.

• Container in errore o restart loop: controlla i log con docker compose logs e cerca errori su database, permessi o variabili mancanti.
• Porta occupata: verifica con ss -ltnp se un altro servizio sta già usando la porta scelta.
• Database non inizializzato: il container del DB può richiedere tempo o parametri corretti; guarda i log del database e la presenza dei volumi persistenti.
• Problemi DNS o proxy: se AWX deve scaricare immagini o contattare servizi esterni, prova curl -I https://registry-1.docker.io o il registry usato dal deployment.
• Permessi sui volumi: se i path montati non sono scrivibili dall’utente del container, il servizio fallisce all’avvio.

Per isolare il layer, fai sempre una verifica in ordine: sistema operativo, Docker, container, HTTP locale, reverse proxy, login web. Questa sequenza evita di perdere tempo sul front-end quando il guasto è nel backend.

Aggiornare AWX senza rompere l’istanza

Un’installazione fatta bene deve essere aggiornabile. Prima di ogni update:

1. salva la versione corrente del repository o del tag;
2. esegui un backup dei volumi persistenti e del database;
3. leggi le note di release della versione che vuoi installare;
4. ferma lo stack in modo controllato;
5. aggiorna immagini e configurazioni;
6. riavvia e verifica login, job e inventari.

Se usi Docker Compose, il flusso tipico è:

docker compose down
# backup volumi e database
docker compose pull
docker compose up -d

Il rollback deve essere altrettanto semplice: ripristino del repository alla release precedente, riavvio dello stack e, se necessario, ripristino dei volumi dal backup. Senza backup dei dati applicativi, l’update non è reversibile in modo serio.

Backup e manutenzione operativa

AWX non va considerato solo come servizio da installare, ma come piattaforma da mantenere. Pianifica backup periodici di almeno tre elementi: database, volumi persistenti e file di configurazione del deployment.

Verifica anche i log rotati e lo spazio disco. Se la partizione si riempie, AWX può degradare in modo poco evidente: job falliti, task bloccati, interfaccia lenta. Un controllo semplice e utile è questo:

df -h
sudo du -sh /var/lib/docker/* 2>/dev/null | sort -h

Se il server è esposto su Internet, aggiorna regolarmente il sistema e i container, limita l’accesso al pannello con firewall o VPN e usa credenziali robuste. La superficie d’attacco di una piattaforma di automazione come AWX va trattata con lo stesso rigore di un pannello di amministrazione sensibile.

Conclusione operativa

Su Debian 12, AWX si installa in modo ragionevolmente pulito con Docker e Compose, a patto di partire da una macchina aggiornata, dimensionata correttamente e con persistenza ben definita. La parte critica non è tanto l’avvio iniziale, quanto la disciplina operativa: versioni fissate, backup, reverse proxy corretto e controlli sui log.

Se vuoi ridurre gli errori, lavora sempre in questo ordine: sistema, Docker, deployment, accesso locale, proxy, hardening. Così isoli rapidamente il layer rotto e eviti cambi inutili su un’installazione che già funziona.

Assunzione: il caso trattato è una singola VM Debian 12 senza Kubernetes, con accesso sudo e necessità di pubblicare AWX via web.