Héberger Garage sur un VPS : votre stockage objet compatible S3

Ce que Garage est, et ce qu'il n'est pas

Ce que Garage fait bien sur un VPS

• API S3 standard : compatible avec aws CLI, rclone, mc, restic, les SDK Python/Go/Rust et la quasi-totalité des clients S3 du marché.
• Empreinte mémoire minime : quelques mégaoctets au repos — il cohabite sans friction avec un serveur web, une base de données ou un reverse proxy sur le même VPS.
• Pas de dépendance externe : ni PostgreSQL, ni Redis, ni etcd. Le moteur de métadonnées est embarqué (LMDB ou SQLite au choix).
• Réplication optionnelle : en mono-nœud, un seul disque suffit ; en multi-nœuds, Garage réplique les objets entre machines, même sur des sites différents.
• Licence AGPLv3 franche : aucune fonctionnalité réservée à une édition payante, pas de limite sur le volume ni sur le nombre de compartiments.
• Sous-domaines virtuels : Garage gère le routing <bucket>.s3.votre-domaine.com, ce qu'attendent certains clients S3 et SDK.

Prérequis : dimensionner votre VPS pour un storage bucket

curl -fsSL https://get.docker.com | sh

Configuration minimale du storage bucket

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "<64 caractères hexadécimaux>"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.votre-domaine.com"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "<jeton d'administration>"

Déployer Garage et créer votre premier compartiment S3

1. 01

   Créer la structure de répertoires

   Commencez par créer un dossier de travail et le fichier de configuration :

   mkdir -p /opt/garage/config
   openssl rand -hex 32   # → copiez ce secret dans rpc_secret
   openssl rand -base64 32 | tr -d '=' | head -c 40  # → admin_token

   Écrivez le garage.toml dans /opt/garage/config/, en remplaçant les deux jetons générés ci-dessus.

2. 02

   Écrire le Compose et démarrer

   Depuis la version 2.3, Garage monte une grappe d'un seul nœud et crée son premier compartiment automatiquement, à partir de variables d'environnement. Cela évite la séquence manuelle layout assign / layout apply / bucket create / key create :

   services:
     garage:
       image: dxflrs/garage:v2.3.0
       restart: unless-stopped
       command: ["/garage", "-c", "/etc/garage/garage.toml", "server", "--single-node", "--default-bucket"]
       environment:
         GARAGE_DEFAULT_BUCKET: mon-compartiment
         GARAGE_DEFAULT_ACCESS_KEY: GK<30 hex>
         GARAGE_DEFAULT_SECRET_KEY: <64 hex>
       ports:
         - "127.0.0.1:3900:3900"
         - "127.0.0.1:3903:3903"
       volumes:
         - ./config:/etc/garage
         - garage-meta:/var/lib/garage/meta
         - garage-data:/var/lib/garage/data
   
   volumes:
     garage-meta:
     garage-data:

   L'image est distroless : pas de shell, entrypoint vide. La commande doit nommer le binaire en chemin absolu (/garage) et passer le fichier de configuration (-c). Sans ces deux éléments, le conteneur boucle sur No such file or directory.

   La clé d'accès S3 doit avoir la forme GK suivi de 30 caractères hexadécimaux exactement — c'est la forme que Garage attend.

   Démarrez :

   docker compose up -d

3. 03

   Vérifier que l'API répond

   Un appel anonyme sur l'API S3 doit répondre 403 — c'est le signe que le service est vivant et refuse une requête non signée :

   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3900/
   # 403 → l'API répond

   L'interface d'administration répond 200 avec le jeton :

   curl -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:3903/v2/ListBuckets

   Si vous obtenez connection refused, le conteneur n'a pas démarré — vérifiez docker compose logs garage.

4. 04

   Exposer l'API derrière nginx et un certificat TLS

   Ne publiez jamais le port 3900 directement sur l'interface publique. Publiez-le sur la boucle locale et laissez nginx faire le proxy et le certificat TLS. Un bloc minimal pour s3.votre-domaine.com :

   server {
       listen 443 ssl;
       server_name s3.votre-domaine.com *.s3.votre-domaine.com;
       ssl_certificate /etc/letsencrypt/live/s3.votre-domaine.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/s3.votre-domaine.com/privkey.pem;
       location / {
           proxy_pass http://127.0.0.1:3900;
           proxy_set_header Host $host;
       }
   }

   Le certificat wildcard *.s3.votre-domaine.com couvre les sous-domaines par compartiment. Utilisez certbot en mode DNS-01 pour l'obtenir. C'est ce que fait l'installation en un clic du Marketplace.

5. 05

   Tester avec un client S3

   Avec les variables d'environnement positionnées, aws CLI fonctionne sans modification :

   export AWS_ACCESS_KEY_ID=GK...
   export AWS_SECRET_ACCESS_KEY=...
   export AWS_DEFAULT_REGION=garage
   
   # Lister les compartiments
   aws --endpoint-url https://s3.votre-domaine.com s3 ls
   
   # Déposer un fichier
   aws --endpoint-url https://s3.votre-domaine.com s3 cp monFichier.txt s3://mon-compartiment/
   
   # Avec rclone
   rclone lsd garage:mon-compartiment

   Pour restic, configurez la variable RESTIC_REPOSITORY=s3:https://s3.votre-domaine.com/mon-compartiment et RESTIC_PASSWORD — la commande restic init initialise le dépôt de sauvegardes.

Cas d'usage courants d'un storage bucket S3 auto-hébergé

Ce qu'on déploie derrière Garage

• Sauvegardes restic ou Borg : configurez votre dépôt de backup en pointant vers s3:https://s3.votre-domaine.com/backups. La compatibilité S3 est native dans restic depuis sa première version.
• Origine d'un site statique : stockez les assets compilés de votre frontend et servez-les via nginx ou Cloudflare en mode proxy. Aucune requête S3 signée n'atteint le client final.
• Stockage d'uploads applicatifs : vos applications Laravel, Django ou Rails peuvent écrire dans Garage via leur SDK S3 habituel, sans changer une ligne de code — seul l'endpoint change.
• Artefacts CI/CD : GitHub Actions ou GitLab CI peuvent pousser les artefacts de build vers Garage avec aws s3 cp, au même titre que vers S3 d'AWS.
• Logs et métriques d'archivage : Loki, Vector ou Fluentd savent écrire dans un stockage objet compatible S3 pour l'archivage long terme.
• Partage de fichiers entre services : deux conteneurs sur le même VPS ou sur deux VPS différents accèdent au même compartiment via l'API S3, sans montage NFS.

Garage vs alternatives S3 auto-hébergées

Faites défiler le tableau

Ce qu'il faut garder en tête