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.

This guide will help you deploy Garage as a single-node server and interact with it. This is the recommended first step before moving on to configuring a multi-node cluster.
Single-node deployments provide no redundancy for your data and should not be used in production.

​
Prerequisites

Before you begin, make sure you have:
  • A Linux, macOS, or Windows system
  • OpenSSL installed (for generating secure credentials)
  • Python (optional, for AWS CLI)

​
Installation

1

Download Garage

Download the latest Garage binary for your platform:
wget https://garagehq.deuxfleurs.fr/download/
Place the binary in your $PATH:
sudo cp garage /usr/local/bin/
sudo chmod +x /usr/local/bin/garage
Verify the installation:
garage --version
You can also use your distribution’s package manager if a binary package is available, or build from source if needed.
2

Create Configuration File

Generate a configuration file with secure random secrets:
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
This configuration uses /tmp for data storage, which is erased on system reboot. For persistent storage, change metadata_dir and data_dir to permanent locations.
Set the configuration file location:
export GARAGE_CONFIG_FILE=$(pwd)/garage.toml
3

Configure Access Credentials

Set up a default access key and bucket using environment variables (available in Garage v2.3.0+):
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"
Save these credentials securely - you’ll need them to access your bucket!
4

Start Garage Server

Launch Garage with automatic single-node configuration:
garage server --single-node --default-bucket
The flags do the following:
  • --single-node: Automatically configures a single-node cluster without data replication
  • --default-bucket: Creates a default access key and bucket using the environment variables
For Garage versions before v2.3.0, these flags are not available. You’ll need to follow the manual configuration steps at the end of this guide.
5

Verify Cluster Status

In a new terminal, check that Garage is running correctly:
export GARAGE_CONFIG_FILE=$(pwd)/garage.toml
garage status
You should see output like:
==== HEALTHY NODES ====
ID                Hostname  Address         Tags       Zone  Capacity  DataAvail         Version
563e1ac825ee3323  linuxbox  127.0.0.1:3901  [default]  dc1   19.9 GiB  19.5 GiB (97.6%)  v2.3.0

​
Using Garage with AWS CLI

Now that Garage is running, let’s upload and download files using the AWS CLI.
1

Install AWS CLI

python -m pip install --user awscli
Verify installation:
aws --version
You need at least AWS CLI v1.29.0 or v2.13.0 to use the AWS_ENDPOINT_URL environment variable.
2

Configure AWS CLI

Create a configuration file to store your Garage credentials:
cat > ~/.awsrc <<EOF
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'

aws --version
EOF
Load the configuration:
source ~/.awsrc
You can create multiple configuration files for different Garage clusters or access keys. Switch between them by sourcing the appropriate file.
3

Test Upload and Download

List your buckets:
aws s3 ls
You should see your default bucket:
2026-03-04 10:30:45 default-bucket
Upload a file:
aws s3 cp /proc/cpuinfo s3://default-bucket/cpuinfo.txt
List objects in the bucket:
aws s3 ls s3://default-bucket
Download the file:
aws s3 cp s3://default-bucket/cpuinfo.txt /tmp/cpuinfo.txt
Verify the download:
cat /tmp/cpuinfo.txt

​
Using Docker

If you prefer to run Garage in a 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
To execute Garage commands in the container: 
docker exec garage-container /garage status
This Docker command does not create persistent volumes. Add volume mounts for your data and metadata directories to persist data across container restarts.

​
Alternative S3 Clients

Garage is compatible with many S3 clients:

Minio Client

Fast and feature-rich CLI client

s3cmd

Popular command-line S3 client

rclone

Versatile cloud storage manager

Cyberduck

GUI client for macOS and Windows
See the S3 compatibility documentation for a complete list of supported features and clients.

​
Troubleshooting

Ensure that:
  • Your configuration file is readable by the user running Garage
  • The metadata_dir and data_dir exist and are writable
  • No other service is using ports 3900-3903
Check the logs for detailed error messages:
RUST_LOG=garage=debug garage server --single-node --default-bucket
Verify that:
  • Garage is running (garage status should work)
  • Your AWS credentials are correctly exported (echo $AWS_ACCESS_KEY_ID)
  • The endpoint URL is correct (http://localhost:3900)
  • Your AWS CLI version is recent enough (v1.29.0+ or v2.13.0+)
The quick start configuration uses /tmp for storage, which is cleared on reboot. Update your garage.toml to use permanent directories:
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
Create these directories and ensure they’re writable by the Garage user.

​
Manual Configuration (Pre-v2.3.0)

If you’re using Garage before v2.3.0, the --single-node and --default-bucket flags are not available. Follow these manual steps:
1

Start Garage

garage server
2

Create Cluster Layout

In a new terminal:
export GARAGE_CONFIG_FILE=$(pwd)/garage.toml
garage status
Note the node ID from the output, then assign it a zone and capacity:
garage layout assign -z dc1 -c 1G <node_id>
garage layout apply --version 1
3

Create Bucket and Key

Create a bucket:
garage bucket create default-bucket
Create an access key:
garage key create my-key
Note the Key ID and Secret Key from the output.Grant permissions:
garage bucket allow --read --write --owner default-bucket --key my-key

​
Next Steps

Multi-Node Cluster

Set up a production-ready multi-node deployment

Configuration Reference

Learn about all configuration options

S3 Compatibility

Check which S3 features are supported

Static Website Hosting

Host static websites from Garage buckets

Build docs developers (and LLMs) love

Get started for freeTalk to us