RustFS con Docker Compose: creare uno storage S3 self-hosted

Hai bisogno di uno storage compatibile con Amazon S3, ma vuoi conservare i dati sulla tua infrastruttura? RustFS è un sistema di object storage open source e self-hosted che puoi installare con Docker Compose. Espone un’API compatibile con S3 e offre una console web per gestire bucket e oggetti ed è un’ottima alternativa a MinIO, progetto che ha cessato lo sviluppo opensource.

In questa guida vediamo come installare RustFS con Docker Compose, creare un bucket, caricare e scaricare file con AWS CLI e proteggere lo storage con credenziali, accesso limitato e backup. Useremo un’installazione semplice su un solo server, adatta per iniziare e per capire come funziona uno storage S3 privato.

Cos’è RustFS e a cosa serve

RustFS è un sistema di archiviazione a oggetti scritto in Rust. Invece di organizzare i dati principalmente come cartelle e file condivisi via SMB o NFS, li rende disponibili come oggetti all’interno di bucket, attraverso un’API compatibile con Amazon S3.

Questo lo rende interessante per applicazioni, script e strumenti di backup che permettono di configurare un endpoint S3 personalizzato. Puoi usarlo, per esempio, come destinazione di test per un’applicazione web, archivio per file generati da un servizio o storage privato raggiungibile dalla tua rete.

Compatibile con S3 non significa identico ad Amazon S3. RustFS supporta le operazioni più comuni, ma alcune API e funzionalità specifiche di AWS o di altri prodotti S3 potrebbero comportarsi diversamente. Prima di usarlo con un’applicazione importante, prova le operazioni di cui hai davvero bisogno.

Come funzionerà questa installazione

Installeremo RustFS come singolo container Docker con:

• porta 9000 per l’API S3;
• porta 9001 per la console web;
• un volume Docker persistente per gli oggetti;
• credenziali impostate nel file .env;
• porte esposte soltanto sull’interfaccia locale del server.

Questa modalità usa un solo nodo e un solo volume. Non aggiunge ridondanza: se il disco si guasta e non hai un backup, puoi perdere i dati. Le configurazioni RustFS con più dischi o più nodi sono un argomento distinto e richiedono una progettazione adeguata.

Prerequisiti

Prima di iniziare ti servono:

• un server Linux, un VPS o un mini PC con Docker Engine e Docker Compose – ti consigliamo Debian 13;
• spazio su disco sufficiente per gli oggetti che vuoi archiviare;
• accesso SSH al server;
• facoltativamente, AWS CLI sul computer da cui vuoi provare l’API S3.

Verifica che Docker Compose sia disponibile con il comando:

docker compose version

In questa guida useremo il comando docker compose, con uno spazio, e non il vecchio eseguibile docker-compose.

1. Crea la cartella del progetto

Collegati al server tramite SSH e crea una directory dedicata:

mkdir -p ~/rustfs
cd ~/rustfs

Qui salverai il file Compose, le impostazioni e gli eventuali archivi di backup. Gli oggetti caricati su RustFS verranno invece conservati in un volume Docker persistente.

2. Prepara le credenziali

RustFS usa una access key e una secret key. Non usare le credenziali predefinite riportate in alcuni esempi online: sono pubbliche e non sono adatte a un’installazione reale.

Per generare una secret key casuale puoi usare:

openssl rand -hex 32

Copia il risultato, poi crea un file chiamato .env:

nano .env

Inserisci i seguenti valori, sostituendo la chiave di esempio e scegliendo una access key univoca:

RUSTFS_ACCESS_KEY=rustfs-admin-personale
RUSTFS_SECRET_KEY=INCOLLA_QUI_LA_CHIAVE_CASUALE_GENERATA

Proteggi il file: contiene credenziali che possono dare accesso allo storage.

chmod 600 .env

Per le applicazioni che useranno lo storage, crea in seguito credenziali dedicate con i soli permessi necessari, anziché riutilizzare le credenziali amministrative.

3. Crea il file Docker Compose

All’interno della cartella ~/rustfs, crea il file:

nano docker-compose.yml

Incolla questa configurazione:

services:
  rustfs:
    image: rustfs/rustfs:1.0.0
    container_name: rustfs
    restart: unless-stopped
    environment:
      RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY}
      RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY}
      RUSTFS_VOLUMES: /data
      RUSTFS_ADDRESS: ":9000"
      RUSTFS_CONSOLE_ENABLE: "true"
      RUSTFS_CONSOLE_ADDRESS: ":9001"
    ports:
      - "127.0.0.1:9000:9000"
      - "127.0.0.1:9001:9001"
    volumes:
      - rustfs-data:/data

volumes:
  rustfs-data:

La configurazione usa il tag stabile 1.0.0, anziché latest: così un successivo docker compose pull non cambia automaticamente versione. Prima di aggiornare, leggi le note della release di destinazione e crea un backup.

Il volume rustfs-data conserva i dati quando il container viene riavviato o ricreato. Non eseguire docker compose down -v se vuoi mantenerli: l’opzione -v rimuove anche i volumi del progetto.

Le porte sono associate a 127.0.0.1: questo permette l’accesso dal server stesso e tramite tunnel SSH, ma non espone direttamente API e console sulla rete, così da aumentare un po’ la sicurezza.

4. Avvia RustFS

Controlla che il file Compose sia valido:

docker compose config --quiet

Poi avvia RustFS:

docker compose up -d

Verifica lo stato del container:

docker compose ps

Per leggere gli ultimi messaggi di avvio:

docker compose logs --tail=100 rustfs

Dal server puoi inoltre controllare che l’API risponda:

curl -fsS http://127.0.0.1:9000/health/ready

Se il container non si avvia, controlla i log e verifica che le porte 9000 e 9001 non siano già occupate.

5. Apri la console con un tunnel SSH

Poiché la porta della console non è esposta sulla rete, apri un tunnel SSH dal tuo computer. Sostituisci utente e IP-DEL-SERVER con i valori reali:

ssh -L 9001:127.0.0.1:9001 \
    -L 9000:127.0.0.1:9000 \
    utente@IP-DEL-SERVER

Lascia aperta la sessione SSH. Sul tuo computer visita:

http://127.0.0.1:9001

Accedi alla console con la access key e la secret key definite nel file .env. Il tunnel inoltra anche la porta 9000: potrai quindi provare l’API S3 dal tuo computer senza esporla sulla rete.

Se sul tuo computer la porta 9000 o 9001 è già occupata, usa una porta locale differente nella parte a sinistra dei due punti nel comando SSH e apri l’indirizzo corrispondente nel browser.

6. Crea il primo bucket S3

Dalla console di RustFS apri la sezione dei bucket e seleziona l’opzione per crearne uno nuovo. Come esempio useremo:

archivio-privato

Un bucket è un contenitore logico per gli oggetti. Puoi creare bucket separati per applicazioni, ambienti o tipi di dati, ad esempio backup-test, file-app o documenti-progetto.

Per iniziare, mantieni il bucket privato. Non rendere pubblici gli oggetti se non hai un motivo preciso e una policy di accesso configurata consapevolmente.

7. Prova RustFS con AWS CLI

Con il tunnel SSH ancora aperto, configura sul tuo computer un profilo AWS CLI dedicato a RustFS:

aws configure --profile rustfs

Quando richiesto, inserisci:

• AWS Access Key ID: il valore di RUSTFS_ACCESS_KEY;
• AWS Secret Access Key: il valore di RUSTFS_SECRET_KEY;
• Default region name: us-east-1;
• Default output format: json.

Il profilo si chiama “AWS” perché stai usando AWS CLI, ma i comandi seguenti raggiungeranno RustFS grazie al parametro --endpoint-url. Impostalo sempre: senza endpoint personalizzato rischi di interrogare il servizio AWS anziché il tuo server.

Elenca i bucket:

aws --profile rustfs \
  --endpoint-url http://127.0.0.1:9000 \
  s3api list-buckets

Crea un piccolo file di prova:

printf 'Ciao da RustFS\n' > prova-rustfs.txt

Caricalo nel bucket:

aws --profile rustfs \
  --endpoint-url http://127.0.0.1:9000 \
  s3 cp prova-rustfs.txt \
  s3://archivio-privato/prove/prova-rustfs.txt

Controlla che l’oggetto sia presente:

aws --profile rustfs \
  --endpoint-url http://127.0.0.1:9000 \
  s3 ls s3://archivio-privato/prove/

Scarica infine una copia per verificare che l’oggetto sia leggibile:

aws --profile rustfs \
  --endpoint-url http://127.0.0.1:9000 \
  s3 cp \
  s3://archivio-privato/prove/prova-rustfs.txt \
  prova-rustfs-scaricata.txt

Se elenco, caricamento e download funzionano, hai verificato le operazioni S3 essenziali della tua installazione.

8. Collegare un’applicazione a RustFS

Quando un software supporta uno storage “S3 compatible” o un “custom S3 endpoint”, in genere devi configurare:

• Endpoint: l’indirizzo dell’API RustFS, sulla porta 9000;
• Bucket: il nome del bucket creato;
• Region: us-east-1, salvo configurazioni diverse;
• Access key e secret key: preferibilmente credenziali dedicate all’applicazione;
• Addressing style: path-style, se il client offre questa opzione.

Un container collegato alla stessa rete Docker di RustFS può usare http://rustfs:9000 come endpoint. Un’applicazione installata su un’altra macchina, invece, non può usare 127.0.0.1 per raggiungere questo server: dovrai predisporre una connessione di rete controllata, una VPN o un endpoint HTTPS.

Non presumere che ogni programma compatibile con Amazon S3 sia automaticamente compatibile con tutte le funzionalità di RustFS. Prova caricamento, lettura, cancellazione e, se necessari, multipart upload, versioning e policy con la specifica applicazione che userai.

9. Accesso dalla rete e HTTPS

La configurazione iniziale è intenzionalmente limitata al server locale. Se vuoi permettere ad altri computer o servizi di raggiungere RustFS, pianifica prima come proteggerli.

Per una rete domestica puoi valutare una VPN e regole firewall che consentano l’accesso soltanto ai dispositivi autorizzati. Se scegli un reverse proxy con HTTPS, considera separatamente:

• l’endpoint S3 sulla porta 9000;
• la console amministrativa sulla porta 9001.

La console non dovrebbe essere liberamente accessibile da Internet. Anche l’API S3 richiede TLS, credenziali dedicate e controlli di rete. Quando configuri un proxy davanti all’API, verifica con AWS CLI che richieste firmate, upload e download funzionino attraverso l’hostname HTTPS definitivo.

Se usi già Nginx Proxy Manager, puoi partire dalla nostra guida su reverse proxy e SSL con Docker Compose, evitando però di trattare RustFS come una normale applicazione web: l’endpoint S3 richiede test specifici delle richieste firmate e dei trasferimenti di file.

10. Backup dei dati

Il volume Docker rende i dati persistenti dopo un riavvio del container, ma persistenza non significa backup. Questa installazione usa un solo nodo e un solo volume: guasti del disco, cancellazioni accidentali e problemi del server possono compromettere gli oggetti.

Per creare una copia coerente del volume, arresta temporaneamente RustFS. Prima individua il nome effettivo del volume montato su /data:

cd ~/rustfs

VOLUME=$(docker inspect rustfs \
  --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}')

printf '%s\n' "$VOLUME"

Se il comando stampa un nome di volume, ferma il container e crea l’archivio:

docker compose stop rustfs

docker run --rm \
  -v "$VOLUME:/source:ro" \
  -v "$PWD:/backup" \
  alpine \
  tar -czf /backup/rustfs-data-backup.tar.gz -C /source .

docker compose start rustfs

L’archivio viene creato nella cartella del progetto: spostane una copia fuori dal server. Salva separatamente anche docker-compose.yml e il file .env, custodendo quest’ultimo in modo sicuro perché contiene le credenziali.

Un backup è affidabile solo se riesci a ripristinarlo. Prova periodicamente il recupero su un’istanza separata e verifica che bucket e oggetti siano leggibili. Per archivi molto grandi, valuta una procedura di backup dedicata invece di un unico file tar.gz.

11. Aggiornare RustFS

Prima di cambiare versione, leggi le note di rilascio, verifica la compatibilità delle funzioni che usi e crea un backup dei dati.

Quando avrai scelto una nuova versione stabile, aggiorna il tag image nel file docker-compose.yml. Poi esegui:

docker compose config --quiet
docker compose pull rustfs
docker compose up -d rustfs
docker compose logs --tail=100 rustfs
curl -fsS http://127.0.0.1:9000/health/ready

Non eliminare il volume rustfs-data durante l’aggiornamento. Dopo il riavvio, ripeti almeno una prova di elenco bucket, caricamento e download con il tuo client S3.

Problemi comuni

La console non si apre dal mio PC

È previsto se provi a visitare direttamente IP-DEL-SERVER:9001: la porta è associata soltanto a 127.0.0.1 del server. Apri il tunnel SSH e visita http://127.0.0.1:9001 sul computer da cui hai creato il tunnel.

AWS CLI si collega al servizio sbagliato

Controlla che ogni comando includa --endpoint-url http://127.0.0.1:9000 e che il tunnel SSH sia ancora attivo. Senza endpoint personalizzato, AWS CLI usa gli endpoint AWS.

La porta 9000 o 9001 è già occupata

Cambia la porta a sinistra dei due punti nella sezione ports del Compose. Mantieni invece coerenti le porte interne e gli indirizzi configurati per i client.

Un client S3 restituisce errori di firma

Verifica endpoint, region, credenziali, orario del sistema e modalità path-style. Se usi HTTPS tramite reverse proxy, esegui i test utilizzando esattamente l’hostname e lo schema che userà l’applicazione.

Conclusioni

RustFS con Docker Compose permette di creare uno storage S3 self-hosted con pochi componenti: un container, credenziali personalizzate e un volume persistente. La console facilita la gestione dei bucket, mentre AWS CLI consente di verificare subito che l’API funzioni.

Per andare oltre il laboratorio, non fermarti al comando docker compose up -d: limita l’accesso di rete, usa HTTPS dove necessario, assegna permessi minimi alle applicazioni e mantieni backup esterni con prove periodiche di ripristino.

FAQ su RustFS

Cos’è RustFS?

RustFS è un sistema open source di object storage compatibile con molte operazioni dell’API Amazon S3. Permette di creare bucket e archiviare oggetti sulla propria infrastruttura.

RustFS è un’alternativa a MinIO?

Può essere valutato come alternativa per alcuni utilizzi di storage compatibile con S3. Non dare però per scontata la compatibilità di tutte le API, degli strumenti amministrativi o delle funzioni avanzate: verifica i requisiti della tua applicazione.

Quali porte usa RustFS?

Nella configurazione di questa guida, la porta 9000 serve l’API S3 e la porta 9001 serve la console web. Sono entrambe esposte solo sull’interfaccia locale del server.

Il volume Docker è sufficiente a proteggere i dati?

No. Il volume conserva i dati quando il container viene ricreato, ma non protegge da guasti del disco, errori o cancellazioni. Servono copie esterne e test di ripristino.

Posso usare RustFS con AWS CLI?

Sì. Configura credenziali e region, poi aggiungi l’opzione --endpoint-url ai comandi AWS CLI per indirizzarli alla tua istanza RustFS.

RustFS richiede più dischi?

No, può funzionare anche con un singolo volume come in questa guida. Questa modalità non offre ridondanza: per esigenze di disponibilità e protezione dei dati maggiori, occorre progettare una configurazione differente.

Posso usare RustFS come unica destinazione dei backup?

È sconsigliabile affidare l’unica copia dei dati a un’istanza RustFS sullo stesso server o disco dei dati originali. Se lo usi come destinazione di backup, prevedi ulteriori copie indipendenti e verifica periodicamente i ripristini.