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.