51 07/04/2026 9 min

Installare CockroachDB su Debian 12

Su Debian 12 la strada corretta è usare il repository ufficiale CockroachDB oppure il pacchetto standalone scaricato dal sito del progetto. Per un’installazione ripetibile e gestibile nel tempo, il repository APT è la scelta più pulita: consente aggiornamenti controllati, integrazione con systemd e verifiche più semplici in fase di manutenzione.

Prima di iniziare, chiarisco il contesto operativo: l’installazione non modifica in modo aggressivo il sistema, ma aggiunge un servizio database che può consumare CPU, RAM e disco in modo significativo. Se stai lavorando su una macchina di produzione, verifica prima spazio libero, policy di backup e porte esposte.

Prerequisiti e controlli iniziali

Su Debian 12 servono privilegi amministrativi e connettività verso i mirror Debian e verso il repository CockroachDB. È utile verificare subito architettura, versione del sistema e spazio disponibile.

cat /etc/debian_version
uname -m
df -h /
free -h

Atteso: Debian 12, architettura amd64 o arm64 supportata, spazio libero sufficiente per binari, log e dati. Se il disco è già saturo o quasi saturo, fermati prima di installare: CockroachDB ha bisogno di margine reale per file di log, dati e compattazione interna.

Se il nodo è dietro firewall, prepara anche l’apertura delle porte che userai. In installazione singola le porte tipiche sono la 26257 per il traffico SQL e cluster, e la 8080 per la console web. Non aprirle in modo indiscriminato su Internet: limita l’esposizione alla rete amministrativa o al reverse proxy di fiducia.

Repository APT ufficiale

La procedura più stabile è importare la chiave del repository e aggiungere la sorgente APT. Su sistemi moderni conviene usare il keyring in /usr/share/keyrings invece del vecchio apt-key, che è deprecato.

sudo apt update
sudo apt install -y curl ca-certificates gpg

Scarica e registra la chiave del repository in modo corretto:

curl -fsSL https://binaries.cockroachdb.com/cockroachdb.key | sudo gpg --dearmor -o /usr/share/keyrings/cockroachdb.gpg

Aggiungi il repository APT. Per Debian 12 puoi usare la distribuzione “bookworm” se il repository la espone come target compatibile. Se il progetto cambia naming o disponibilità nel tempo, va verificato sulla documentazione ufficiale prima di procedere.

echo 'deb [signed-by=/usr/share/keyrings/cockroachdb.gpg] https://binaries.cockroachdb.com/apt/debian bookworm main' | sudo tee /etc/apt/sources.list.d/cockroachdb.list

Aggiorna l’indice e installa il pacchetto:

sudo apt update
sudo apt install -y cockroachdb

Se il pacchetto non viene trovato, la prima cosa da controllare è la riga del repository in /etc/apt/sources.list.d/cockroachdb.list e l’output di apt update. Gli errori più comuni sono chiave non valida, URL errato o naming della distribuzione non supportato.

Verifica dell’installazione

Dopo l’installazione controlla che il binario sia presente e che la versione sia coerente con quella attesa.

cockroach version

Atteso: output con versione del server e del client. Se il comando non esiste, verifica il pacchetto installato con dpkg -l | grep cockroach e il path del binario con command -v cockroach.

È utile anche verificare i file installati dal pacchetto:

dpkg -L cockroachdb | sed -n '1,40p'

Questo ti conferma dove sono finiti binario, documentazione e possibili unit file. Se il pacchetto cambia nome nel tempo, il controllo con dpkg -l evita di andare a tentativi.

Avvio come servizio systemd

Su Debian 12 CockroachDB può essere avviato manualmente o come servizio. Per un server persistente, systemd è la scelta corretta. Se il pacchetto include l’unit file, puoi abilitarlo direttamente; se non lo include, conviene creare un’unit custom con parametri espliciti.

Prima verifica se l’unit esiste:

systemctl list-unit-files | grep -i cockroach

Se trovi un’unit già pronta, controlla il suo stato:

systemctl status cockroachdb --no-pager

Se invece devi creare una configurazione minima, conviene definire utente dedicato, directory dati e directory log. Esempio di base:

sudo useradd -r -m -d /var/lib/cockroach -s /usr/sbin/nologin cockroach
sudo install -o cockroach -g cockroach -d /var/lib/cockroach /var/log/cockroach

Avvia poi il nodo in modalità singola con listen address e store espliciti. In un ambiente reale questi parametri vanno adattati alla topologia del cluster.

sudo -u cockroach cockroach start \
  --store=/var/lib/cockroach \
  --advertise-addr=127.0.0.1:26257 \
  --listen-addr=0.0.0.0:26257 \
  --http-addr=0.0.0.0:8080 \
  --background

Questo comando è utile per un test locale, ma non basta per una configurazione robusta. In produzione conviene incapsulare i parametri in un file di configurazione o in un’unit systemd ben tracciata.

Configurazione minima consigliata

La configurazione di CockroachDB dipende dal caso d’uso. Se vuoi un nodo singolo per test, bastano pochi parametri. Se devi costruire un cluster, servono almeno indirizzo di advertising, storage path persistente e una strategia di bootstrap controllata.

Una baseline ragionevole per una macchina dedicata è questa:

  • utente dedicato non privilegiato
  • directory dati persistente su disco separato o volume dedicato
  • porta SQL non esposta pubblicamente senza filtro
  • console web limitata a rete admin o localhost

Per il servizio systemd, un’unit minimale può essere impostata in modo chiaro e revisionabile. Esempio:

[Unit]
Description=CockroachDB
After=network-online.target
Wants=network-online.target

[Service]
User=cockroach
Group=cockroach
ExecStart=/usr/bin/cockroach start --store=/var/lib/cockroach --advertise-addr=127.0.0.1:26257 --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080
Restart=on-failure
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Salvala in /etc/systemd/system/cockroachdb.service, poi ricarica systemd e abilita il servizio.

sudo systemctl daemon-reload
sudo systemctl enable --now cockroachdb

Atteso: il servizio risulta active (running). Se va in errore, i primi log da leggere sono quelli di journalctl.

journalctl -u cockroachdb -n 100 --no-pager

Inizializzazione del database

Un’installazione software non basta: il database va inizializzato correttamente. Per un cluster singolo, il primo avvio può richiedere bootstrap automatico oppure un avvio con flag dedicati, a seconda della versione e del modello operativo scelto.

Per una prova rapida in locale, puoi avviare il nodo e verificare la console web su http://127.0.0.1:8080. In alternativa, usa il client SQL integrato per controllare il server.

cockroach sql --host=127.0.0.1:26257 -e 'SHOW DATABASES;'

Atteso: risposta SQL valida, anche con solo i database di default. Se il comando fallisce, i casi più probabili sono servizio non avviato, porta non in ascolto o mismatch tra indirizzo di ascolto e indirizzo di connessione.

Controlla anche le porte in ascolto:

ss -lntp | grep -E '26257|8080'

Se non vedi nulla, il processo non è in esecuzione oppure è partito con parametri errati.

Firewall e accesso remoto

Se il nodo deve essere raggiunto da altre macchine, apri le porte con criterio. Su Debian il firewall può essere gestito da nftables, ufw o da regole esterne sul provider. Non esporre la console web senza protezione.

Con ufw, per esempio, puoi limitare l’accesso alla rete di amministrazione:

sudo ufw allow from 10.0.0.0/24 to any port 26257 proto tcp
sudo ufw allow from 10.0.0.0/24 to any port 8080 proto tcp

Se usi nftables, crea regole equivalenti e verifica che la policy di default non blocchi traffico necessario al cluster. Per un’installazione singola in LAN, la regola più sicura è consentire solo le origini note.

Controlli di salute

Dopo l’installazione, verifica tre livelli: servizio, porta e query SQL. Questa sequenza riduce il tempo perso quando il problema è in realtà altrove.

  1. Servizio: systemctl is-active cockroachdb deve restituire active.
  2. Porta: ss -lntp | grep cockroach deve mostrare 26257 e, se abilitata, 8080.
  3. SQL: cockroach sql -e 'SELECT version();' deve rispondere senza errori.

Se la console web è abilitata, apri la pagina di stato e controlla che il nodo sia visibile e che non compaiano warning su storage o replica. In un cluster vero, questa è la prima spia per capire se il sistema è sano o solo “avviato”.

Gestione aggiornamenti

Con il repository APT, gli aggiornamenti seguono il flusso standard Debian. Prima di aggiornare in produzione, pianifica una finestra e verifica la compatibilità di versione, soprattutto se il nodo fa parte di un cluster esistente.

sudo apt update
apt list --upgradable | grep -i cockroach

Prima di applicare un upgrade, documenta versione attuale, stato del cluster e backup recenti. Il rollback a volte non è banale se nel frattempo sono cambiate le strutture interne o il formato dei dati. Se l’installazione è solo per test, il rollback più semplice è rimuovere il pacchetto e cancellare i dati di prova.

Per disinstallare il software senza toccare i dati, usa la rimozione del pacchetto. Per rimuovere anche i dati, fallo solo se sei certo di non aver bisogno del contenuto del datastore.

sudo systemctl disable --now cockroachdb
sudo apt remove -y cockroachdb

Se devi fare pulizia completa in un ambiente non produttivo, rimuovi anche le directory dati e log solo dopo verifica esplicita del proprietario del servizio e del backup disponibile.

Problemi tipici e diagnosi rapida

Se l’installazione non va a buon fine, i casi più frequenti sono pochi e riconoscibili. Una diagnosi rapida evita di cambiare troppe variabili insieme.

  • Repository non raggiungibile: apt update mostra errori TLS o 404.
  • Chiave mancante: APT segnala firma non verificabile o repository non trusted.
  • Servizio non parte: journalctl -u cockroachdb mostra errori su permessi o porta occupata.
  • Database non risponde: ss -lntp non mostra 26257 o il processo è crashato.

In caso di conflitto porta, controlla quale processo sta già occupando la porta:

sudo lsof -iTCP:26257 -sTCP:LISTEN
sudo lsof -iTCP:8080 -sTCP:LISTEN

Se il problema è un permesso sulle directory dati, verifica ownership e mode di /var/lib/cockroach e /var/log/cockroach. Il servizio deve poter scrivere nei path configurati, altrimenti parte e si ferma subito.

Scelta architetturale per produzione

Se l’obiettivo non è un test locale ma un uso reale, la vera decisione non è “come installarlo”, ma come posizionarlo nel tuo stack. CockroachDB rende meglio quando è trattato come database distribuito con storage affidabile, rete stabile e topologia chiara. Su una singola VM può andare bene per laboratorio o ambienti leggeri, ma non sostituisce automaticamente una progettazione di alta disponibilità.

Per una base sana, definisci almeno questi punti prima dell’installazione definitiva:

  • numero di nodi e modalità di bootstrap
  • storage persistente e policy di backup
  • esposizione rete e accesso amministrativo
  • monitoraggio di CPU, RAM, disco e latenza SQL

Se il nodo è destinato a un’applicazione PHP, Node.js o Java, integra subito il monitoring dell’applicazione con quello del database. Il collo di bottiglia spesso non è il binario, ma la latenza di storage o la saturazione della rete interna.

Comando rapido per una prova locale

Se vuoi soltanto verificare che il pacchetto funzioni su Debian 12, questa sequenza minima è sufficiente come test non persistente:

sudo apt update
sudo apt install -y curl ca-certificates gpg
curl -fsSL https://binaries.cockroachdb.com/cockroachdb.key | sudo gpg --dearmor -o /usr/share/keyrings/cockroachdb.gpg
echo 'deb [signed-by=/usr/share/keyrings/cockroachdb.gpg] https://binaries.cockroachdb.com/apt/debian bookworm main' | sudo tee /etc/apt/sources.list.d/cockroachdb.list
sudo apt update
sudo apt install -y cockroachdb
cockroach version

Se questo flusso si completa, hai conferma che repository, pacchetto e binario funzionano sul sistema. Da lì puoi passare alla parte operativa: servizio, storage persistente, networking e hardening.

Assunzione: i comandi sopra sono eseguiti su Debian 12 amd64/arm64 con accesso root o sudo e con repository CockroachDB ancora disponibile nella forma indicata; in caso contrario va verificato il naming corrente nel repository ufficiale prima di applicarli.