Gestire il proprio storage a oggetti compatibile con S3 ci permette di avere il pieno controllo su dove risiedono i nostri dati, elimina i costi per singola richiesta e rimuove la dipendenza da provider cloud esterni. In questa guida vedremo l’installazione di Garage su un singolo nodo.

Cos’è Garage

Garage è un sistema di storage a oggetti distribuito e leggero, progettato specificamente per girare su hardware comune, anche su nodi geograficamente separati, implementa l’API S3, quindi qualsiasi strumento o applicazione esistente che comunica con AWS S3 funzionerà con Garage senza modifiche.

A differenza di soluzioni più pesanti come Ceph, Garage è pensato specificamente per cluster distribuiti su più aree geografiche (anche con connessioni non eccellenti) e per carichi di lavoro medio-piccoli.

Perché scegliere Garage

Esistono diverse soluzioni S3 self-hosted (MinIO è la più popolare), ma Garage presenta alcune caratteristiche distintive:

  • Scritto in Rust: è efficiente in termini di memoria e ha un’impronta binaria ridotta.
  • Progettato per distribuzioni geo-distribuite: utilizza un modello di consistenza debole.
  • Binario singolo: nessuna dipendenza esterna.
  • Gestione dei guasti: gestisce il fallimento dei nodi con grazia e senza interventi manuali.
  • Licenza Apache 2.0: nessuna funzionalità riservata solo alla versione “enterprise”.

Per piccoli team o homelab, la semplicità di Garage è il suo principale punto di forza.

Requisiti

  • Server Ubuntu 22.04 o 24.04.
  • Almeno 1 GB di RAM (consigliati 2+ GB).
  • Volume di storage montato su un percorso noto (es. /data).
  • Porte del firewall aperte: 3900 (RPC), 3901 (S3), 3902 (web), 3903 (admin).

Installazione e configurazione

Per prima cosa andiamo a scaricare l’ultima versione del binario di Garage, quindi dal terminale:

wget https://garagehq.deuxfleurs.fr/_releases/v2.2.0/x86_64-unknown-linux-musl/garage

Una volta effettuato il download spostiamo il binario all’interno della directory /usr/local/bin/, quindi digitiamo sul terminale:`

sudo mv garage /usr/local/bin/garage

E successivamente rendiamolo eseguibile:

sudo chmod +x /usr/local/bin/garage

Adesso verifichiamo che tutto funzioni correttamente:

garage --version

Riceveremo a video una risposta simile a questa:

E’ buona norma far girare Garage con un utente dedicato, quindi andiamo a creare un utente col nome garage, sul nostro terminale digitiamo:

sudo useradd --system --no-create-home --shell /bin/false garage

Successivamente creiamo le varie cartelle che ci serviranno per dati e metadati:

sudo mkdir -p /data/garage/data
sudo mkdir -p /data/garage/meta
sudo mkdir -p /etc/garage

Adesso impostiamo i permessi all’utente garage creato poco fa:

sudo chown -R garage:garage /data/garage
sudo chown -R garage:garage /etc/garage

Passiamo adesso alla configurazione di Garage, per farlo andiamo a creare un file di config TOML:

sudo nano /etc/garage/garage.toml

Ed inseriamo il seguente contenuto:

# File di configurazione di Garage (giuxfila.com/blog/installare-garage)

# Definiamo quante copie di ogni oggetto vengono salvate,
# lasciare 1 per una config a nodo singolo
# in un cluster in produzione il valore standard da inserire è 3
replication_factor = 1

# Porta RPC per la comunicazione interna al cluster
rpc_bind_addr = "0.0.0.0:3900"

# Chiave segreta per l'autenticazione del cluster - generatela con: openssl rand -hex 32
rpc_secret = "il_tuo_segreto_generato_qui"

# Directory per i metadati del database
metadata_dir = "/data/garage/meta"

# Directory per lo storage dei dati degli oggetti
data_dir = "/data/garage/data"

[s3_api]
# Indirizzo di bind dell'API S3
api_bind_addr = "0.0.0.0:3901"

# Identificatore della regione S3 (qualsiasi stringa)
s3_region = "us-east-1"

# Abilita gli URL stile: bucket.s3.esempio.com (opzionale)
# s3_root_domain = ".s3.esempio.com"

[s3_web]
# Endpoint web per l'hosting di siti statici (opzionale)
bind_addr = "0.0.0.0:3902"
root_domain = ".web.esempio.com"
index = "index.html"

[admin]
# Porta dell'API di amministrazione
api_bind_addr = "0.0.0.0:3903"

Salviamo il file con CTRL+X e successivamente confermiamo con “Y”.

Mi raccomando, genera un secret RPC abbastanza forte col comando openssl rand -hex 32 e sostituisci il_tuo_segreto_generato_qui con l’output ottenuto.

A questo punto andiamo a creare il servizio Systemd, quindi sul terminale digitiamo:

sudo nano /etc/systemd/system/garage.service

Ed inseriamo il seguente contenuto:

[Unit]
Description=Garage S3-compatible object storage
After=network.target
Documentation=https://garagehq.deuxfleurs.fr/documentation/

[Service]
Type=simple
User=garage
Group=garage

# Path to the config file
ExecStart=/usr/local/bin/garage -c /etc/garage/garage.toml server

Restart=on-failure
RestartSec=5

# Resource limits
LimitNOFILE=65536

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/data/garage

[Install]
WantedBy=multi-user.target

Salviamo il file con CTRL+X e successivamente confermiamo con “Y”, a questo dobbiamo solamente abilitare il servizio ed avviarlo:

sudo systemctl daemon-reload
sudo systemctl enable --now garage

Verifichiamo che tutto sia partito senza intoppi:

sudo systemctl status garage

riceveremo a video una risposta simile a questa:

Anche per un setup a nodo singolo, dobbiamo definire una zona ed una capacità. Per prima cosa dobbiamo ottenere l’id del nodo:

sudo -u garage garage -c /etc/garage/garage.toml node id

Riceveremo a video una risposta simile a questa:

L’ID del nodo è la stringa esadecimale prima della @, quindi impostiamo la zona e la capacità digitando:

sudo -u garage garage -c /etc/garage/garage.toml layout assign \
  8f68d2fbdc5baf9c484960da61f428696c7655370792982986ee071434b23b9b \
  --zone dc1 \
  --capacity 1024

Attenzione: --capacity 1024(è il “peso” del nodo), indica quanta quota di dati questo nodo deve ospitare, espressa in GB, nelle recenti release il valore minimo richiesto è di 1024.

A video riceveremo una risposta simile a questa:

Adesso andiamo verifichiamo il layout proposto con il comando:

sudo -u garage garage -c /etc/garage/garage.toml layout show

E successivamente applichiamo definitivamente il layout:

sudo -u garage garage -c /etc/garage/garage.toml layout apply --version 1

Come ultimo procedimento andiamo a verificare lo stato del cluster:

sudo -u garage garage -c /etc/garage/garage.toml status

Creazione del bucket e chiavi d’accesso

Una volta effettuata la prima configurazione, non ci resta che creare il nostro primo bucket di dati, per farlo digitiamo:

sudo -u garage garage -c /etc/garage/garage.toml bucket create mio-bucket

Per verificare tutti i bucket possiamo digitare il comando:

sudo -u garage garage -c /etc/garage/garage.toml bucket list

A questo punto generiamo le credenziali d’accesso, che andranno utilizzate poi nei programmi o script:

sudo -u garage garage -c /etc/garage/garage.toml key create mia-chiave

Importante: Questo comando restituirà un Access Key ID e una Secret Access Key. Copiamoli subito e salviamoli in un posto sicuro (come un password manager), perché la Secret Key non verrà più mostrata.

Infine dobbiamo collegare questa chiave al bucket e concedere le autorizzazioni di lettura e scrittura:

sudo -u garage garage -c /etc/garage/garage.toml bucket allow \
  mio-bucket \
  --read \
  --write \
  --key mia-chiave