Come Fare Deploy su un VPS con Kamal (Guida Completa)

Kamal non gira sul tuo VPS. È uno strumento di deploy che installi sulla tua macchina o sul tuo runner CI, e che si collega al server via SSH per fare il suo lavoro. Basecamp l’ha creato per rilasciare applicazioni Rails senza Kubernetes, ma fa il deploy di qualunque cosa si costruisca in un’immagine Docker.

Questa distinzione cambia ciò che stai cercando. Il VPS è la destinazione di Kamal, quindi deve essere abbastanza capiente per la tua applicazione, i suoi database e qualche giorno di versioni dell’immagine. L’impronta di Kamal sul server è invece nulla.

Cosa Kamal lascia davvero sul server

kamal setup si collega via SSH (come root per impostazione predefinita, autenticato con la tua chiave SSH) ed esegue tre passaggi: installa Docker se non c’è, avvia gli accessori dichiarati, poi fa il deploy dell’applicazione. Dopodiché l’host esegue:

• kamal-proxy — un piccolo proxy HTTP che occupa le porte 80 e 443, ottiene i certificati Let’s Encrypt e trattiene le richieste in ingresso durante un deploy finché il container sostitutivo non è pronto.
• I container dell’applicazione — un gruppo per ogni ruolo definito in config/deploy.yml.
• Gli accessori — Postgres, Redis o gli altri servizi elencati nella configurazione.

Kamal in sé è una gem (gem install kamal, 2.12.0 al momento in cui scriviamo) e non lascia alcun demone in esecuzione.

Requisiti

Prima di iniziare, procurati:

• Un VPS con un’installazione Linux pulita e accesso SSH come root tramite chiave (Ubuntu 24.04 è una scelta sensata)
• Un registry di container da cui il server possa scaricare — Docker Hub, GitHub Container Registry o quello del tuo provider
• Ruby in locale per gem install kamal; senza Ruby puoi eseguire Kamal da un’immagine container, con qualche limite
• Un Dockerfile funzionante per la tua applicazione

Scegliere il provider VPS

Poiché il server esegue solo container, valuta i provider sull’affidabilità della rete, sul margine di disco e sulla rapidità con cui puoi ricostruire un host:

Per un confronto completo, consulta il nostro confronto VPS.

DigitalOcean è il punto di partenza più semplice, perché la sua documentazione copre esattamente il lavoro a livello di host che Kamal non fa al posto tuo: regole del firewall, swap e aggiornamenti automatici.

Preparare il server

1. Crea il VPS con un’immagine minimale di Ubuntu 24.04 e la tua chiave SSH associata.
2. Verifica che l’accesso SSH come root funzioni, perché è così che Kamal si collega per impostazione predefinita:

ssh root@ip-del-tuo-vps

3. Apri solo il necessario. kamal-proxy termina TLS sul server, quindi bastano le porte 22, 80 e 443:

ufw allow 22,80,443/tcp && ufw enable

Non devi installare Docker: se manca, ci pensa Kamal al primo kamal setup.

Installare Kamal e scrivere la configurazione

Sulla tua macchina, nella cartella dell’applicazione:

gem install kamal
kamal init

kamal init crea config/deploy.yml. Una configurazione minima funzionante richiede un nome di servizio, un’immagine e almeno un host:

service: myapp
image: your-registry-user/myapp

servers:
  web:
    hosts:
      - 203.0.113.10

registry:
  username: your-registry-user
  password:
    - KAMAL_REGISTRY_PASSWORD

proxy:
  ssl: true
  host: app.example.com

I segreti stanno in .kamal/secrets, che Kamal legge al momento del deploy. Cerca prima .kamal/secrets-common, poi .kamal/secrets:

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

Tieni quel file fuori dal controllo di versione e prendi il valore dall’ambiente della shell o da un gestore di password.

Il primo deploy

kamal setup

Questo singolo comando installa Docker, avvia gli accessori, costruisce e carica l’immagine e avvia l’applicazione. Ogni deploy successivo si riduce a:

kamal deploy

Per vedere cosa sta girando sull’host:

kamal app containers

Dove viene costruita l’immagine

Per impostazione predefinita Kamal costruisce in locale, sulla macchina da cui lo lanci, e poi carica sul registry. Il server si limita a scaricare. Se il tuo portatile è arm64 e il VPS è amd64, fissa l’architettura di destinazione oppure indica a Kamal un builder remoto:

builder:
  arch: amd64
  remote: ssh://[email protected]

La compilazione incrociata tramite emulazione è abbastanza lenta da notarsi a ogni deploy. Se il VPS è la tua unica macchina amd64, può fare anche da builder — ma allora dimensionalo per una build Docker e non solo per far girare l’app, il che di solito significa salire di un piano.

Dimensionare il disco

Kamal conserva container e immagini vecchie sul server, così kamal rollback può riavviare una versione precedente senza tornare al registry. Per impostazione predefinita li rimuove dopo tre giorni. Calcola i dati della tua applicazione più circa tre giorni di versioni dell’immagine e i loro layer di base condivisi.

Un’immagine da 1 GB rilasciata qualche volta al giorno sta comodamente sui 40 GB NVMe di Hetzner. Un’immagine da 3 GB riempie un disco da 25 GB nel giro di una settimana, e un disco pieno rompe il deploy successivo, non quello in corso — il che rende il problema facile da trascurare finché non diventa urgente.

Il passaggio senza interruzioni

kamal-proxy sposta il traffico sul nuovo container solo quando questo risponde 200 a GET /up. Ne discendono due cose:

• La tua applicazione ha bisogno di un endpoint /up. Rails ne fornisce uno; gli altri framework di solito richiedono poche righe.
• Quell’endpoint deve restituire 200 soltanto quando l’applicazione è davvero in grado di servire richieste. Se risponde prima che le connessioni al database siano pronte, gli utenti finiscono troppo presto sul nuovo container.

Se il controllo di salute non passa mai, il deploy va in timeout e Kamal lascia il vecchio container a servire il traffico.

Mettere in sicurezza il deploy

• Kamal si collega come root via SSH: disattiva completamente l’autenticazione con password e affidati alle chiavi.
• Lascia gestire TLS a kamal-proxy. Aggiungere un secondo reverse proxy davanti complica soltanto il percorso dei certificati.
• Aggiungi swap sugli host da 4 GB. Durante un deploy il vecchio e il nuovo container convivono per un momento, e un host che inizia a fare swap proprio allora diventa abbastanza lento da sforare il timeout del controllo di salute.
• Tieni la password del registry in .kamal/secrets e non in config/deploy.yml, che finisce nel repository.

Consigli finali

• Lancia kamal deploy dalla CI non appena il percorso manuale funziona. La configurazione è identica, cambia solo l’origine dei segreti.
• kamal rollback [versione] è immediato finché la vecchia immagine è ancora su disco: controlla con kamal app containers che una destinazione di rollback esista ancora.
• Il deploy di una seconda applicazione sullo stesso host è supportato in Kamal 2 — kamal-proxy instrada per nome host, quindi a ogni applicazione basta il proprio service e il proprio proxy.host.

Per approfondire la scelta del server sottostante, consulta il nostro confronto VPS.