Running with Docker

Garage can be run in Docker containers, making it easy to deploy and manage across different environments. This guide covers both simple single-node setups and production multi-node deployments.

Docker Image

Garage’s official Docker image is hosted on Docker Hub as dxflrs/garage.

Always use a specific version tag (e.g., v2.2.0) rather than latest to ensure consistency and avoid unexpected updates.

Check the Docker Hub page for the most recent available versions.

Quick Start (Single Node)

For development or testing, you can quickly start a single-node Garage instance.

Pull the Docker image

docker pull dxflrs/garage:v2.2.0

Create a configuration file

Create a garage.toml configuration file in your current directory:

cat > garage.toml <<EOF
metadata_dir = "/tmp/meta"
data_dir = "/tmp/data"
db_engine = "sqlite"

replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "$(openssl rand -base64 32)"
metrics_token = "$(openssl rand -base64 32)"
EOF

Set up credentials (optional)

Configure automatic bucket and key creation:

export GARAGE_DEFAULT_ACCESS_KEY="GK$(openssl rand -hex 16)"
export GARAGE_DEFAULT_SECRET_KEY="$(openssl rand -hex 32)"
export GARAGE_DEFAULT_BUCKET="default-bucket"

Run the container

docker run \
  -d \
  --name garage-container \
  -p 3900:3900 -p 3901:3901 -p 3902:3902 -p 3903:3903 \
  -v $(pwd)/garage.toml:/etc/garage.toml \
  -e GARAGE_DEFAULT_ACCESS_KEY \
  -e GARAGE_DEFAULT_SECRET_KEY \
  -e GARAGE_DEFAULT_BUCKET \
  dxflrs/garage:v2.2.0 \
  /garage server --single-node --default-bucket

This command does NOT create persistent volumes for data. If the container stops, all data will be lost. For persistent storage, see the production deployment section below.

On Linux, you can use --network host instead of port mappings for better performance:

docker run -d --name garage-container --network host ...

Interacting with the Container

Use Docker exec to run Garage CLI commands inside the container:

# Check cluster status
docker exec garage-container /garage status

# Create an alias for convenience
alias garage="docker exec -ti garage-container /garage"

# Now you can use the alias
garage status
garage bucket list

Production Deployment

For production environments, you need persistent storage and proper configuration.

Directory Structure

Set up the following directories on your host:

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

/etc/garage.toml - Configuration file
/var/lib/garage/meta/ - Metadata storage (use SSD if possible)
/var/lib/garage/data/ - Data storage (can be on HDD)

Production Configuration

Create a production configuration at /etc/garage.toml:

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"

replication_factor = 3

compression_level = 2

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "<this node's public IP>:3901"
rpc_secret = "<RPC secret>"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage"
index = "index.html"

Set rpc_public_addr to the node’s public IP address for multi-node clusters
Generate rpc_secret with openssl rand -hex 32 and use the same value on all nodes
Use replication_factor = 3 for production (requires at least 3 nodes)