Installare HAProxy su VPSie con deploy in un clic

HAProxy su VPSie: quando ha senso usarlo

HAProxy serve quando vuoi mettere davanti ai tuoi servizi un bilanciamento affidabile, health check seri, terminazione TLS, rate limiting di base e una gestione ordinata del traffico. Se hai un'app web, uno o più backend, oppure vuoi esporre un singolo endpoint stabile mentre dietro cambi versioni e host, HAProxy è una scelta solida.

Su una VPS VPSie l'installazione è lineare: il punto non è tanto mettere su il pacchetto, quanto farlo in modo che il deploy non rompa il servizio. La logica corretta è questa: prima installi e testi HAProxy in ascolto su una porta non critica, poi colleghi il deploy, infine sposti il traffico sulla porta pubblica. Così hai un percorso reversibile.

In questa guida assumo un server Linux recente con accesso root o sudo, e un'app web che gira su una porta locale o su più host backend. Se usi pannelli o orchestratori, la logica non cambia: cambia solo dove imposti gli upstream e come fai il deploy.

Prerequisiti operativi prima di toccare il traffico

Prima di installare, verifica questi punti minimi:

• accesso SSH stabile alla VPS;
• porta libera per il frontend di test, ad esempio 8080;
• backend raggiungibile in locale o in rete privata;
• backup della configurazione corrente se HAProxy è già presente;
• piano di rollback: ripristino della config precedente e riavvio del servizio.

Se il server è già in produzione, evita di sostituire la configurazione live in un solo colpo. Lavora con una configurazione nuova, validala con il comando di test e solo dopo fai reload.

Installazione del pacchetto

Su Debian o Ubuntu:

sudo apt update
sudo apt install haproxy

Su RHEL, AlmaLinux o Rocky:

sudo dnf install haproxy

Subito dopo controlla che il binario e il servizio siano presenti:

haproxy -v
systemctl status haproxy --no-pager

Atteso: versione stampata dal comando e servizio installato, anche se non ancora avviato. Se il pacchetto non esiste nei repository standard della tua distribuzione, va verificata la policy del repository della VPS o l'immagine base usata. In quel caso non inventare workaround: prima identifica il repository corretto o il canale supportato dal provider.

Struttura minima della configurazione

Il file principale è di solito /etc/haproxy/haproxy.cfg. Prima di modificarlo, fai una copia di sicurezza:

sudo cp /etc/haproxy/haproxy.cfg /etc/haproxy/haproxy.cfg.bak.$(date +%F-%H%M)

Una configurazione minima per un frontend HTTP con backend locale può essere questa:

global
    log /dev/log local0
    log /dev/log local1 notice
    maxconn 4096
    user haproxy
    group haproxy
    daemon

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5s
    timeout client  30s
    timeout server  30s
    option  redispatch

frontend fe_http
    bind *:80
    default_backend be_app

backend be_app
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server app1 127.0.0.1:8080 check

Questa base copre il caso più semplice: HAProxy ascolta su 80 e inoltra verso un'app sulla 8080. Se la tua app ha una health endpoint diversa, sostituisci /health con il path corretto. Se il backend non risponde con 200, i check falliranno e il nodo verrà marcato down.

Se hai più backend, aggiungi più righe server. Se vuoi bilanciare tra host diversi, usa i loro IP o nomi risolvibili localmente.

Verifica della configurazione prima del reload

Questo è il passaggio che evita il downtime inutile. Non riavviare a occhi chiusi. Valida la sintassi:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Atteso: messaggio di configurazione valida e nessun errore di parsing. Se c'è un errore, correggilo prima di procedere. Gli errori più comuni sono:

• indentazione o keyword sbagliata;
• porta già occupata;
• backend non raggiungibile nella health check;
• opzioni incompatibili con la versione installata.

Controlla anche se la porta 80 è già occupata da Apache, Nginx o un altro listener:

sudo ss -lntp | grep ':80 '

Se la porta è in uso, non forzare. Decidi chi deve stare davanti: HAProxy oppure il web server. In un setup classico con HAProxy come reverse proxy, il web server deve spostarsi dietro su una porta locale o su un socket diverso.

Avvio e abilitazione del servizio

Quando la configurazione è valida, abilita e avvia il servizio:

sudo systemctl enable --now haproxy

Verifica lo stato:

systemctl status haproxy --no-pager

Atteso: stato active (running). Se il servizio non parte, guarda i log recenti:

journalctl -u haproxy -n 50 --no-pager

Qui trovi in genere errori di binding, configurazione o permessi. Se il demone non può aprire la porta 80, il problema è quasi sempre un conflitto di bind o un contesto di sicurezza che blocca l'ascolto.

Deploy in un clic: come collegarlo senza rompere il proxy

Il concetto di deploy in un clic varia a seconda del pannello o della piattaforma che usi, ma la regola resta la stessa: il deploy deve aggiornare l'app dietro HAProxy, non sostituire HAProxy in modo cieco.

Il flusso corretto è questo:

1. il deploy pubblica la nuova versione dell'app su una porta o directory controllata;
2. HAProxy continua a puntare al backend stabile;
3. fai un reload dell'app o del backend;
4. verifichi che la health check torni OK;
5. solo dopo, se serve, promuovi il traffico completo.

Se il tuo “deploy in un clic” è un pulsante nel pannello VPSie o in un tool collegato, cerca questi campi o equivalenti:

• porta di ascolto dell'app;
• host/IP backend;
• health check path;
• eventuale hook post-deploy per reload del servizio applicativo;
• comando di validazione o test URL.

Se il pannello supporta script post-deploy, usa un comando minimo e reversibile. Esempio concettuale:

systemctl reload myapp

Se invece il deploy carica direttamente un container o un processo nuovo, fai in modo che la porta finale resti la stessa o che HAProxy venga aggiornato con un reload controllato. Il punto critico è non lasciare HAProxy su un backend morto dopo il deploy.

Termina TLS davanti a HAProxy se vuoi separare traffico e app

Se il sito deve andare in HTTPS, HAProxy può terminare TLS e parlare in chiaro col backend interno. È una scelta comune e funziona bene quando il backend è su rete privata o sullo stesso host.

In quel caso il frontend diventa simile a questo:

frontend fe_https
    bind *:443 ssl crt /etc/haproxy/certs/site.pem
    http-request set-header X-Forwarded-Proto https
    default_backend be_app

Il certificato deve essere in un file PEM leggibile da HAProxy. Se usi più domini, puoi gestire più certificati o un bundle adeguato. Dopo ogni modifica del certificato, valida sempre la configurazione e fai reload, non restart, se vuoi ridurre l'interruzione.

Controllo rapido:

openssl s_client -connect tuo-dominio:443 -servername tuo-dominio 

Atteso: catena TLS corretta e certificato coerente col dominio. Se il browser segnala mismatch o il handshake fallisce, il problema è nel file PEM, nel percorso del certificato o nella sintassi del bind.

Health check e failover di base

Uno dei motivi per usare HAProxy è distinguere un backend vivo da uno solo teoricamente raggiungibile. Per questo i check devono essere realistici. Un semplice TCP check spesso non basta: il servizio può accettare connessioni ma restituire pagine vuote o errori applicativi.

Con health check HTTP puoi verificare un endpoint dedicato, meglio se leggero e senza dipendenze pesanti. L'endpoint dovrebbe rispondere 200 solo quando l'app è realmente pronta.

Per osservare lo stato dei backend, abilita una pagina di stats solo se serve davvero e proteggila con accesso ristretto:

listen stats
    bind 127.0.0.1:8404
    stats enable
    stats uri /stats
    stats refresh 10s

Qui la scelta di bind su 127.0.0.1 evita esposizione inutile. Se ti serve accesso remoto, metti una ACL o un reverse proxy con autenticazione davanti. Non esporre la pagina stats sulla rete pubblica senza controllo.

Problemi tipici dopo l'installazione

I problemi più frequenti non sono “HAProxy non funziona”, ma uno di questi casi:

• la porta 80 o 443 è già occupata;
• il backend non risponde entro i timeout;
• la health check è troppo rigida;
• il deploy cambia porta o path senza aggiornare HAProxy;
• il certificato TLS è nel formato sbagliato.

Per isolare velocemente il layer, usa questi controlli:

curl -I http://127.0.0.1
curl -I http://127.0.0.1:8080
journalctl -u haproxy -n 30 --no-pager

Se il backend risponde e HAProxy no, il problema è nel proxy. Se il backend non risponde già in locale, il problema è nell'app o nel servizio che la ospita. Se tutto funziona in locale ma non da fuori, allora devi guardare firewall, security group, routing o DNS.

Rollback pulito se qualcosa va storto

Il rollback deve essere banale. Se hai modificato solo la configurazione, ripristina il backup e ricarica il servizio:

sudo cp /etc/haproxy/haproxy.cfg.bak.YYYY-MM-DD-HHMM /etc/haproxy/haproxy.cfg
sudo haproxy -c -f /etc/haproxy/haproxy.cfg && sudo systemctl reload haproxy

Se il problema è un backend introdotto dal deploy, torna temporaneamente al backend precedente nella configurazione e fai reload. Questo riduce il blast radius perché non tocchi il servizio proxy, ma solo la destinazione del traffico.

Se hai cambiato anche il certificato, conserva sempre una copia del file precedente e verifica che i permessi siano corretti. Un file PEM leggibile solo dall'utente giusto evita errori e riduce l'esposizione dei segreti.

Checklist finale per andare in produzione

Prima di considerare chiuso l'intervento, controlla questi punti:

• HAProxy è attivo con systemctl status haproxy;
• la configurazione valida con haproxy -c -f /etc/haproxy/haproxy.cfg;
• il backend risponde sulla porta o URL attesi;
• la health check è OK e i nodi non risultano down;
• il deploy in un clic aggiorna l'app senza sostituire il proxy;
• hai un rollback con backup della config e ordine di ripristino chiaro.

Assunzione operativa: il server è una VPS Linux standard con systemd, e il deploy in un clic aggiorna l'app dietro HAProxy, non il proxy stesso.

Quando HAProxy non è la scelta giusta

Se hai un solo sito statico senza backend multipli, HAProxy può essere sovradimensionato. In quel caso un web server classico o un CDN davanti possono bastare. HAProxy diventa davvero utile quando hai bisogno di controllo sul traffico, alta disponibilità, health check e transizione ordinata tra versioni.

Se invece il problema è che il sito cade per risorse insufficienti, il proxy non è la cura: prima devi guardare CPU, RAM, I/O disco, limiti del processo e saturazione del database. HAProxy può proteggere e distribuire, ma non compensa un backend strutturalmente sottodimensionato.

La regola pratica è semplice: usa HAProxy quando il collo di bottiglia è nel fronting e nella gestione del traffico; non usarlo come cerotto per un'app che già non regge il carico.