Garage S3: A Lightweight Alternative for Self-Hosted Object Storage

Introduction

Garage is an open-source, distributed object storage service designed specifically for self-hosted environments. It implements the Amazon S3 API, making it compatible with a wide range of existing tools and applications. Unlike traditional object storage solutions, Garage is built with simplicity, resilience, and resource efficiency in mind.

Key Benefits of Garage S3

Lightweight and Resource-Efficient

Garage is designed to run on modest hardware, making it perfect for home labs, small businesses, and edge deployments. It can operate efficiently on ARM devices like Raspberry Pi, consuming minimal CPU and RAM resources.

Geographic Distribution

One of Garage’s standout features is its built-in support for geographic distribution. You can deploy nodes across different locations, ensuring data availability even if entire sites go offline. This makes it ideal for distributed infrastructure scenarios.

S3 Compatibility

Garage implements a substantial portion of the S3 API, allowing you to use familiar tools like s3cmd, AWS CLI, rclone, and many backup solutions without modification. This compatibility ensures easy migration and integration with existing workflows.

No External Dependencies

Unlike many distributed storage systems, Garage doesn’t require external coordination services like ZooKeeper or etcd. It uses its own consensus algorithm, simplifying deployment and reducing points of failure.

Flexible Replication

Garage allows you to configure replication factors on a per-bucket basis, giving you fine-grained control over data redundancy and storage efficiency. You can balance between storage costs and data protection based on your specific needs.

Open Source

Garage is fully open-source under the AGPL-3.0 license, giving you complete control over your data and infrastructure without vendor lock-in.

Installing Garage in Docker

Prerequisites

Before beginning, ensure you have:

  • Docker installed on your system
  • Basic understanding of command-line operations
  • At least 1GB of free disk space for testing

Step 1: Create Directory Structure

First, create directories to store Garage configuration and data:

mkdir -p ~/garage/{data,meta}

Step 2: Generate Configuration File

Create a configuration file at ~/garage/garage.toml:

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"

replication_mode = "none"

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "1799bccfd7411eddcf9ebd316bc1f5287ad12a68094e1c6ac6abde7e6feae1ec"

[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"

Important: Generate your own rpc_secret using:

openssl rand -hex 32

Step 3: Run Garage Container

Launch the Garage container with the following command:

docker run -d \\
  --name garage \\
  -p 3900:3900 \\
  -p 3901:3901 \\
  -p 3902:3902 \\
  -p 3903:3903 \\
  -v ~/garage/garage.toml:/etc/garage.toml \\
  -v ~/garage/data:/var/lib/garage/data \\
  -v ~/garage/meta:/var/lib/garage/meta \\
  dxflrs/garage:v0.9.4 \\
  server

Step 4: Initialize the Cluster

Check the node ID:

docker exec garage garage node id

The output will show your node ID. Use it to configure the cluster:

docker exec garage garage layout assign -z dc1 -c 1G<br>docker exec garage garage layout show<br>docker exec garage garage layout apply --version 1

Step 5: Create Access Credentials

Create a key pair for S3 access:

docker exec garage garage key create my-key

Save the displayed Access Key ID and Secret Access Key.

Step 6: Create a Bucket

Create your first bucket:

docker exec garage garage bucket create my-bucket

Allow your key to access the bucket:

docker exec garage garage bucket allow --read --write my-bucket --key my-key

Step 7: Test Your Setup

Install the AWS CLI if you haven’t already, then configure it:

aws configure set aws_access_key_id
aws configure set aws_secret_access_key

Upload a test file:

echo "Hello Garage!" > test.txt<br>aws s3 cp test.txt s3://my-bucket/ --endpoint-url http://localhost:3900

List bucket contents:

aws s3 ls s3://my-bucket/ --endpoint-url http://localhost:3900

Docker Compose Configuration

For easier management, you can use Docker Compose. Create a <em>docker-compose.yml</em> file:

version: ‘3.8’

version: '3.8'

services:
  garage:
    image: dxflrs/garage:v0.9.4
    container_name: garage
    command: server
    ports:
      - "3900:3900"
      - "3901:3901"
      - "3902:3902"
      - "3903:3903"
    volumes:
      - ./garage.toml:/etc/garage.toml
      - ./data:/var/lib/garage/data
      - ./meta:/var/lib/garage/meta
    restart: unless-stopped

Start the service:

docker-compose up -d

Conclusion

Garage provides a practical, lightweight alternative to commercial object storage solutions. Its Docker-based deployment makes it easy to test and run in various environments. Whether you’re building a home lab, setting up backup storage, or experimenting with distributed systems, Garage offers a compelling combination of simplicity and capability.

For production deployments, consider running multiple nodes for redundancy and reviewing the official documentation for advanced configuration options.