Garage S3

intermediate

Lightweight S3-compatible distributed storage.

Overview

Garage is a lightweight, self-healing distributed object storage system developed by Deuxfleurs that implements the Amazon S3 API. Unlike heavyweight solutions like Ceph or MinIO clusters, Garage is specifically designed for small to medium deployments, running efficiently on modest hardware including Raspberry Pi devices with minimal RAM requirements. The system automatically handles data replication across nodes and provides built-in geo-distribution capabilities without complex configuration. This Docker deployment exposes three distinct services on separate ports: the S3-compatible API on port 3900 for object storage operations, an administrative interface on port 3901 for cluster management, and a web UI on port 3902 for monitoring and basic operations. Garage's architecture separates metadata and data storage into dedicated volumes, enabling efficient data organization and backup strategies while maintaining consistency across distributed nodes. This configuration suits organizations seeking S3-compatible storage without the operational complexity of enterprise solutions like AWS S3 on-premises or large-scale Ceph deployments. Garage excels in environments where simplicity, resource efficiency, and automatic data healing are prioritized over maximum throughput, making it ideal for backup repositories, development environments, and small business file storage needs.

Key Features

S3 API compatibility with support for multipart uploads, versioning, and standard S3 operations
Automatic data replication with configurable replication factor across cluster nodes
Self-healing capabilities that automatically detect and repair data inconsistencies
Geo-distributed storage support for multi-datacenter deployments
Low memory footprint optimized for ARM devices and resource-constrained environments
Built-in web interface for cluster monitoring and basic storage management
Flexible consistency levels from eventual consistency to strong consistency per bucket
Integrated load balancing across storage nodes without external load balancers

Common Use Cases

1Personal cloud storage backend for applications like Nextcloud or Seafile
2Backup target for tools like Restic, Duplicati, or Rclone requiring S3 compatibility
3Development and testing environments needing S3-like storage without AWS costs
4Small business file storage with automatic replication across office locations
5IoT data collection where devices upload sensor data via S3 API
6Media streaming services requiring distributed storage for video and audio files
7Static website hosting with geographic distribution across multiple nodes

Prerequisites

Minimum 512MB RAM per Garage node (1GB recommended for production use)
Available ports 3900, 3901, and 3902 not used by other services
Pre-configured garage.toml file defining cluster layout and replication settings
Basic understanding of S3 concepts like buckets, keys, and access credentials
Network connectivity between nodes if running multi-node deployment
S3-compatible client tools like s3cmd, aws-cli, or Rclone for testing

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  garage: 
3    image: dxflrs/garage:latest
4    container_name: garage
5    restart: unless-stopped
6    volumes: 
7      - ./garage.toml:/etc/garage.toml
8      - garage_data:/var/lib/garage/data
9      - garage_meta:/var/lib/garage/meta
10    ports: 
11      - "3900:3900"
12      - "3901:3901"
13      - "3902:3902"
14
15volumes: 
16  garage_data: 
17  garage_meta:

.env Template

.env

1# Create garage.toml configuration

Usage Notes

1Docs: https://garagehq.deuxfleurs.fr/documentation/
2S3 API on 3900, Admin on 3901, Web UI on 3902
3Create garage.toml: define nodes, replication factor, data paths
4Lightweight: runs on Raspberry Pi, low RAM usage
5Good for small clusters (3-10 nodes), self-healing
6Connect with s3cmd: s3cmd --host localhost:3900 ls

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  garage:
5    image: dxflrs/garage:latest
6    container_name: garage
7    restart: unless-stopped
8    volumes:
9      - ./garage.toml:/etc/garage.toml
10      - garage_data:/var/lib/garage/data
11      - garage_meta:/var/lib/garage/meta
12    ports:
13      - "3900:3900"
14      - "3901:3901"
15      - "3902:3902"
16
17volumes:
18  garage_data:
19  garage_meta:
20EOF
21
22# 2. Create the .env file
23cat > .env << 'EOF'
24# Create garage.toml configuration
25EOF
26
27# 3. Start the services
28docker compose up -d
29
30# 4. View logs
31docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/garage/run | bash

Troubleshooting

Error 'No such file or directory: /etc/garage.toml': Create garage.toml configuration file with node definitions and replication factor before starting container
Connection refused on port 3900: Verify garage.toml contains correct bind addresses and RPC secret is properly configured
Cluster status shows nodes as unavailable: Check firewall rules allow communication on ports 3901-3902 between nodes
S3 operations return 500 errors: Ensure cluster has sufficient healthy nodes to meet the configured replication factor
High memory usage despite low RAM claims: Reduce block_size parameter in garage.toml or increase available container memory
Web UI shows 'Unknown' node status: Verify all nodes share identical RPC secret in their garage.toml configuration

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

garage

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download