Quick Start Guide

Get started with Garage in minutes - from installation to your first upload

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

Garage won't start

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

Cannot connect with AWS CLI

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+)

Files are not persisting after reboot

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