Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/deuxfleurs-org/garage/llms.txt

Use this file to discover all available pages before exploring further.

S3-Compatible Object Storage for Self-Hosted Deployments

Garage is a lightweight, geo-distributed object storage service designed for small to medium-scale self-hosting. Store your data across multiple locations with automatic replication and S3 compatibility.

Get StartedAPI Reference

Quick Start

Get Garage running in minutes with these simple steps

1

Download Garage

Download the latest binary for your platform from the official releases or install via your package manager.
# Place binary in your PATH
sudo cp garage /usr/local/bin/
sudo chmod +x /usr/local/bin/garage
2

Create Configuration

Generate a minimal configuration file with unique secrets:
cat > garage.toml <<EOF
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 = "$(openssl rand -hex 32)"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"

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

Start the Server

Launch Garage with automatic single-node configuration:
export GARAGE_CONFIG_FILE=./garage.toml
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"

garage server --single-node --default-bucket
The --single-node flag automatically configures a single-node cluster. The --default-bucket flag creates a default access key and bucket using the environment variables.
4

Upload Your First Object

Configure the AWS CLI and upload a file:
# Configure AWS CLI
export AWS_ENDPOINT_URL='http://localhost:3900'
export AWS_DEFAULT_REGION='garage'
export AWS_ACCESS_KEY_ID="$GARAGE_DEFAULT_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="$GARAGE_DEFAULT_SECRET_KEY"

# Upload a file
aws s3 cp myfile.txt s3://default-bucket/

# List objects
aws s3 ls s3://default-bucket/

Why Garage?

Built for small-scale self-hosting with enterprise-grade features

Geo-Distributed by Design

Replicate data across multiple physical locations for maximum resilience. Garage handles network partitions and keeps your data available even when nodes go offline.

S3 Compatible

Drop-in replacement for Amazon S3. Use existing S3 tools, libraries, and workflows without modification.

No External Dependencies

Self-contained binary with no database, no RAFT consensus, no ZooKeeper. Just start the server and you’re running.

Lightweight & Fast

Designed for consumer hardware and standard Internet connections. No RAFT bottleneck means better performance across distributed nodes.

Flexible Topology

Add or remove nodes at any time. Garage automatically rebalances data to maintain your desired replication level.

Built-in Web Server

Host static websites directly from S3 buckets with custom domain support. No reverse proxy required.

Explore Documentation

Everything you need to deploy and operate Garage

Installation

Install Garage from binary packages, build from source, or run with Docker

View guides

Deployment

Set up single-node or multi-node clusters with geo-distributed replication

View guides

Operations

Manage cluster layout, perform repairs, monitor health, and handle upgrades

View guides

CLI Reference

Complete command-line reference for cluster administration and configuration

View reference

Ready to Deploy?

Start with a single node and scale to a geo-distributed cluster as your needs grow. Garage makes it easy.

Get Started Now