Host Garage on a VPS: your own S3-compatible storage bucket

What Garage is, and what it is not

What Garage does well on a VPS

• Standard S3 API: compatible with aws CLI, rclone, mc, restic, Python/Go/Rust SDKs and virtually all S3 clients on the market.
• Modest footprint: the project targets modest hardware — it coexists without friction with a web server, database or reverse proxy on the same VPS.
• No external dependency: no PostgreSQL, no Redis, no etcd. The metadata engine is embedded (LMDB or SQLite).
• Optional replication: in single-node mode a single disk is enough; in multi-node mode Garage replicates objects between machines, even across different sites.
• Unencumbered AGPLv3 licence: no feature gated behind a paid edition, no volume or bucket count limits.
• Virtual subdomains: Garage routes <bucket>.s3.your-domain.com, which some S3 clients and SDKs require.

Prerequisites: sizing your VPS for a storage bucket

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

Minimal storage bucket configuration

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 hexadecimal characters>"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.your-domain.com"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "<admin token>"

Deploy Garage and create your first S3 bucket

1. 01

   Create the directory structure

   Create a working directory and configuration file:

   mkdir -p /opt/garage/config
   openssl rand -hex 32   # → paste as rpc_secret
   openssl rand -base64 32 | tr -d '=' | head -c 40  # → admin_token
   
   # S3 credentials for the default bucket, in a root-only .env file
   cd /opt/garage && umask 077
   printf 'GARAGE_DEFAULT_ACCESS_KEY=GK%s\nGARAGE_DEFAULT_SECRET_KEY=%s\n' "$(openssl rand -hex 12)" "$(openssl rand -hex 32)" > .env

   Write garage.toml into /opt/garage/config/, replacing the two generated tokens.

2. 02

   Write the Compose file and start

   Since version 2.3, Garage can bootstrap a single-node cluster and create its first bucket automatically from environment variables. This avoids the manual layout assign / layout apply / bucket create / key create sequence:

   services:
     garage:
       image: dxflrs/garage:v2.5.0
       restart: unless-stopped
       command: ["/garage", "-c", "/etc/garage/garage.toml", "server", "--single-node", "--default-bucket"]
       environment:
         GARAGE_DEFAULT_BUCKET: my-bucket
         GARAGE_DEFAULT_ACCESS_KEY: ${GARAGE_DEFAULT_ACCESS_KEY}
         GARAGE_DEFAULT_SECRET_KEY: ${GARAGE_DEFAULT_SECRET_KEY}
       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:

   The image is distroless: no shell, empty entrypoint. The command must name the binary by absolute path (/garage) and pass the config file (-c). Without both, the container loops on No such file or directory.

   Both credentials come from the .env file created in the previous step, which Compose reads on its own: no secret is written in clear in the file. GK followed by 24 hexadecimal characters, with a 64-character secret, is the shape of the keys Garage generates; since 2.3, an imported key only needs at least 8 characters, and its secret at least 16.

   docker compose up -d

3. 03

   Verify the API is responding

   An anonymous call to the S3 API should return 403 — the correct sign that the service is alive and rejecting unsigned requests:

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

   The admin API returns 200 with the token:

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

   If you get connection refused, the container has not started — check docker compose logs garage.

4. 04

   Expose the API behind nginx and TLS

   Never publish port 3900 directly on the public interface. Bind it to localhost and let nginx handle the proxy and TLS certificate. A minimal block for s3.your-domain.com:

   server {
       listen 443 ssl;
       server_name s3.your-domain.com *.s3.your-domain.com;
       ssl_certificate /etc/letsencrypt/live/s3.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/s3.your-domain.com/privkey.pem;
       client_max_body_size 0;  # otherwise nginx rejects any upload > 1 MB (413)
       location / {
           proxy_pass http://127.0.0.1:3900;
           proxy_set_header Host $host;
           proxy_max_temp_file_size 0;
       }
   }

   The *.s3.your-domain.com wildcard certificate covers per-bucket subdomains. Use certbot in DNS-01 mode to obtain it.

5. 05

   Test with an S3 client

   With the environment variables set, the aws CLI works without modification:

   export AWS_ACCESS_KEY_ID=GK...
   export AWS_SECRET_ACCESS_KEY=...
   export AWS_DEFAULT_REGION=garage
   
   aws --endpoint-url https://s3.your-domain.com s3 ls
   aws --endpoint-url https://s3.your-domain.com s3 cp myfile.txt s3://my-bucket/

   For restic, set RESTIC_REPOSITORY=s3:https://s3.your-domain.com/my-bucket and run restic init.

Common use cases for a self-hosted S3 storage bucket

What people deploy behind Garage

• restic backups: set RESTIC_REPOSITORY=s3:https://s3.your-domain.com/backups. S3 compatibility in restic is native and requires no plugin; Borg, in its stable 1.4 branch, only supports local or SSH repositories.
• Static site origin: store compiled frontend assets and serve them through nginx or Cloudflare in proxy mode. No signed S3 requests reach the end user.
• Application file uploads: Laravel, Django or Rails apps write to Garage through their usual S3 SDK — only the endpoint changes.
• CI/CD artefacts: GitHub Actions or GitLab CI push build artefacts to Garage with aws s3 cp, exactly as with AWS S3.
• Log and metric archiving: Loki, Vector or Fluentd can write to an S3-compatible store for long-term archiving.
• File sharing between services: two containers on the same or different VPS nodes access the same bucket via the S3 API, with no NFS mount.

Garage vs self-hosted S3 alternatives

Scroll the table

Things to keep in mind