Alojar Garage en un VPS: storage bucket S3 propio y autoalojado

Qué es Garage y qué no es

Lo que Garage hace bien en un VPS

• API S3 estándar: compatible con aws CLI, rclone, mc, restic, SDKs de Python/Go/Rust y prácticamente todos los clientes S3 del mercado.
• Huella de memoria mínima: unos pocos megabytes en reposo — convive sin fricción con un servidor web, una base de datos o un proxy inverso en el mismo VPS.
• Sin dependencias externas: ni PostgreSQL, ni Redis, ni etcd. El motor de metadatos está embebido (LMDB o SQLite).
• Replicación opcional: en modo de un nodo basta un disco; en modo multinodo Garage replica objetos entre máquinas, incluso en sitios distintos.
• Licencia AGPLv3 sin restricciones: ninguna función reservada a una edición de pago, sin límite de volumen ni de número de buckets.
• Subdominios virtuales: Garage gestiona el enrutamiento <bucket>.s3.tu-dominio.com, que algunos clientes S3 y SDKs requieren.

Requisitos previos: dimensionar tu VPS para un storage bucket

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

Configuración mínima del 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 caracteres hexadecimales>"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.tu-dominio.com"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "<token de administración>"

Desplegar Garage y crear tu primer bucket S3

1. 01

   Crear la estructura de directorios

   Crea un directorio de trabajo y el archivo de configuración:

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

   Escribe garage.toml en /opt/garage/config/ reemplazando los dos tokens generados.

2. 02

   Escribir el Compose y arrancar

   Desde la versión 2.3, Garage puede inicializar un clúster de un nodo y crear su primer bucket automáticamente a partir de variables de entorno. Esto evita la secuencia manual 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: mi-bucket
         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:

   La imagen es distroless: sin shell, entrypoint vacío. El comando debe nombrar el binario por ruta absoluta (/garage) y pasar el archivo de configuración (-c). La clave de acceso S3 debe ser GK seguida de exactamente 30 caracteres hexadecimales.

   docker compose up -d

3. 03

   Verificar que la API responde

   Una llamada anónima a la API S3 debe devolver 403 — la señal correcta de que el servicio está activo y rechaza peticiones sin firmar:

   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3900/
   # 403 → la API responde

   La API de administración devuelve 200 con el token:

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

4. 04

   Exponer la API detrás de nginx y TLS

   Nunca publiques el puerto 3900 directamente en la interfaz pública. Enlázalo a localhost y deja que nginx gestione el proxy y el certificado TLS:

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

5. 05

   Probar con un cliente S3

   Con las variables de entorno configuradas, la CLI aws funciona sin modificaciones:

   export AWS_ACCESS_KEY_ID=GK...
   export AWS_SECRET_ACCESS_KEY=...
   export AWS_DEFAULT_REGION=garage
   
   aws --endpoint-url https://s3.tu-dominio.com s3 ls
   aws --endpoint-url https://s3.tu-dominio.com s3 cp miarchivo.txt s3://mi-bucket/

   Para restic, configura RESTIC_REPOSITORY=s3:https://s3.tu-dominio.com/mi-bucket y ejecuta restic init.

Casos de uso habituales de un storage bucket S3 autoalojado

Qué se despliega detrás de Garage

• Copias de seguridad con restic o Borg: configura RESTIC_REPOSITORY=s3:https://s3.tu-dominio.com/backups. La compatibilidad S3 en restic es nativa y no requiere plugins.
• Origen de sitio estático: almacena los assets compilados del frontend y sírvelos con nginx o Cloudflare en modo proxy.
• Subida de archivos de aplicaciones: las aplicaciones Laravel, Django o Rails escriben en Garage a través de su SDK S3 habitual — solo cambia el endpoint.
• Artefactos de CI/CD: GitHub Actions o GitLab CI suben artefactos de build a Garage con aws s3 cp, igual que con AWS S3.
• Archivo de logs y métricas: Loki, Vector o Fluentd pueden escribir en un almacén de objetos compatible con S3 para archivo a largo plazo.
• Compartir archivos entre servicios: dos contenedores en el mismo o diferente VPS acceden al mismo bucket a través de la API S3, sin montaje NFS.

Garage vs alternativas S3 autoalojadas

Desplace la tabla

Lo que hay que tener presente