Updates
- 23.10.: Added my Garage WebUI installation instructions. Still tweaking things …
Enterprise-Grade S3-Compatible Storage
In an era where data sovereignty and privacy concerns are at an all-time high, the need for self-hosted alternatives to major cloud providers has never been more pressing. Enter Garage, an innovative open-source distributed object storage system that brings enterprise-grade S3-compatible storage to your own infrastructure.
Developed by Deuxfleurs, a French non-profit organization dedicated to defending individual freedom and rights on the Internet, Garage represents a paradigm shift in how we think about distributed storage. Unlike traditional solutions that require extensive infrastructure and complex setup procedures, Garage was designed from the ground up to be lightweight, resilient, and deployable on heterogeneous hardware.
Garage is on my update radar, as I was looking for an alternative to Minio. Minio decided to remove the web interface in the latest releases of their community edition. Current web interface alternatives are MinIO Console / OpenMaxIO UI .
What Makes Garage Special?
The Philosophy Behind Garage
Garage wasn’t born in a corporate boardroom or university lab. It emerged from the real-world needs of system administrators who understood that not everyone has access to dedicated backbone networks or uniform hardware. The developers recognized a fundamental gap in the market: existing distributed storage solutions were either too complex, too resource-intensive, or designed for homogeneous data center environments.
The result is a storage system that embraces the reality of modern self-hosted infrastructure: mixed hardware, varying network conditions, and the need for operational simplicity without sacrificing reliability.
Core Architecture and Design
At its heart, Garage implements a three-way replication strategy across different zones, ensuring your data remains available even when entire nodes or network segments fail. This isn’t just theoretical resilience – it’s been battle-tested in production environments where network latency can reach 200ms and hardware failures are a fact of life.
The system leverages cutting-edge research in distributed systems, drawing inspiration from:
- Amazon’s Dynamo: For highly available key-value storage patterns
- Conflict-Free Replicated Data Types (CRDTs): Ensuring consistency without coordination overhead
- Maglev Load Balancing: For efficient request distribution
Technical Specifications
System Requirements (2025):
- CPU: Any x86_64 processor from the last decade, or ARMv7/ARMv8
- Memory: Minimum 1GB RAM
- Storage: At least 16GB available space
- Network: Up to 200ms latency tolerance, 50+ Mbps recommended
- Operating System: Any Linux distribution (single binary deployment)
Why Garage Matters in 2025
The Self-Hosting Renaissance
2025 has marked a significant shift in how individuals and organizations approach data storage. With increasing awareness of data privacy, vendor lock-in concerns, and the desire for digital autonomy, self-hosting has moved from niche hobby to mainstream necessity.
Garage addresses several critical pain points that have historically made self-hosted object storage challenging:
Operational Complexity: Traditional solutions like Ceph or GlusterFS require specialized knowledge and significant ongoing maintenance. Garage ships as a single binary with sensible defaults.
Hardware Requirements: Most distributed storage systems assume uniform, high-end hardware. Garage thrives on mixed environments – you can build a cluster from whatever second-hand machines are available.
Network Dependencies: Garage was designed for the real internet, not idealized data center networks. It handles intermittent connectivity, variable latency, and partial network failures gracefully.
S3 Compatibility: The Universal Language of Object Storage
One of Garage’s most compelling features is its comprehensive implementation of the Amazon S3 API. This isn’t just marketing speak – Garage provides genuine compatibility with the vast ecosystem of S3-compatible tools and applications.
Immediate Integration Opportunities:
- Content Management Systems (WordPress, Drupal)
- Media Platforms (Nextcloud, PeerTube)
- Backup Solutions (restic, duplicity, Duplicati)
- Development Tools (Docker registries, Git LFS)
- Static Site Hosting (Hugo, Jekyll, Gatsby)
Getting Started: Docker Compose Installation
The Modern Deployment Approach
While Garage can be deployed as a standalone binary or through various orchestration platforms, Docker Compose offers the perfect balance of simplicity and production-readiness for most self-hosting scenarios.
Pre-Installation Considerations
Before diving into the installation, consider your storage strategy:
Metadata vs. Data Storage: Garage separates frequently-accessed metadata from bulk data storage. Ideally, place metadata on faster storage (SSD) and data on higher-capacity drives (HDD).
Filesystem Choice: For data storage, XFS provides optimal performance. Avoid EXT4 for large object counts due to inode limitations. For metadata storage, consider BTRFS or ZFS for their integrity features, especially if using the default LMDB database engine.
Network Planning: Even for single-node deployments, consider your future scaling needs. Garage’s configuration allows seamless expansion from single-node to multi-node clusters.
Complete Docker Compose Setup
Here’s a production-ready Docker Compose configuration that incorporates current best practices:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
version: '3.8' services: garage: image: dxflrs/garage:v2.0.0 container_name: garage restart: unless-stopped ports: - "3900:3900" # S3 API - "3901:3901" # RPC (internal communication) - "3902:3902" # S3 Web (static website hosting) - "3903:3903" # Admin API - "3904:3904" # K2V API (optional key-value store) volumes: - ./garage.toml:/etc/garage.toml:ro - garage_meta:/var/lib/garage/meta - garage_data:/var/lib/garage/data environment: - RUST_LOG=garage=info healthcheck: test: ["CMD", "/garage", "status"] interval: 30s timeout: 10s retries: 3 start_period: 30s volumes: garage_meta: driver: local driver_opts: type: none o: bind device: ./data/meta garage_data: driver: local driver_opts: type: none o: bind device: ./data/storage networks: default: name: garage_network |
Also checkout Garage UI for a complete docker setup with a web interface or read more about here.
Configuration Deep Dive
The heart of any Garage deployment is the garage.toml configuration file. Here’s a thoroughly commented version that explains each section:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
# Garage Configuration File - Production Ready # Core storage paths metadata_dir = "/var/lib/garage/meta" # Fast storage preferred data_dir = "/var/lib/garage/data" # High capacity storage # Database engine selection db_engine = "lmdb" # Fastest option, use "sqlite" for ARM or 32-bit systems # Automatic backup for metadata metadata_auto_snapshot_interval = "6h" # Regular snapshots for recovery # Cluster configuration replication_factor = 1 # Use 3 for production clusters compression_level = 2 # Balance between CPU usage and storage efficiency # Network configuration rpc_bind_addr = "[::]:3901" rpc_public_addr = "127.0.0.1:3901" # Change to actual IP for clustering rpc_secret = "generated_secret_here" # 64-character hex string # S3 API endpoint configuration [s3_api] s3_region = "garage" api_bind_addr = "[::]:3900" root_domain = ".s3.garage.localhost" # Static website hosting [s3_web] bind_addr = "[::]:3902" root_domain = ".web.garage.localhost" index = "index.html" # Key-Value store API (optional but powerful) [k2v_api] api_bind_addr = "[::]:3904" # Administrative interface [admin] api_bind_addr = "[::]:3903" admin_token = "secure_admin_token" metrics_token = "secure_metrics_token" |
Garage WebUI
A simple admin web UI for Garage, a self-hosted, S3-compatible, distributed object storage service.
Portainer Stack
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
services: garage: image: dxflrs/garage:v2.0.0 container_name: garage volumes: - /docker/data/garage/garage.toml:/etc/garage.toml - /docker/data/garage/meta:/var/lib/garage/meta - /docker/data/garage/data:/var/lib/garage/data restart: unless-stopped ports: - 3900:3900 - 3901:3901 - 3902:3902 - 3903:3903 webui: image: khairul169/garage-webui:latest container_name: garage-webui restart: unless-stopped volumes: - /docker/data/garage/garage.toml:/etc/garage.toml:ro ports: - 3909:3909 environment: API_BASE_URL: "http://garage:3903" S3_ENDPOINT_URL: "https://api.your-domain.net" AUTH_USER_PASS: "admin:hash" |
garage.toml
And the garage.toml setup for one instance, with replication set to one. Still trimming the configuration, but all working for me. Alias web sharing requires a wildcard domain.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
metadata_dir = "/var/lib/garage/meta" data_dir = "/var/lib/garage/data" db_engine = "sqlite" metadata_auto_snapshot_interval = "6h" replication_factor = 1 compression_level = 2 rpc_bind_addr = "[::]:3901" rpc_public_addr = "localhost:3901" # Required rpc_secret = "your rpc secret" [s3_api] s3_region = "garage" api_bind_addr = "[::]:3900" root_domain = "*.api.bucket.your-domain.net" [s3_web] # Optional, if you want to expose bucket as web bind_addr = "[::]:3902" root_domain = "*.web.bucket.your-domain.net" index = "index.html" [admin] # Required api_bind_addr = "[::]:3903" admin_token = "yourtoken!2025!" metrics_token = "yourtokenn!2025!" |
Create Layout
If your unable to create the first layout. Get your node ID after the server started
|
1 2 3 4 5 6 7 8 9 10 |
docker exec -ti garage /garage status > docker exec -ti garage /garage status 2025-05-26T14:37:13.331401Z INFO garage_net::netapp: Connected to 192.168.147.2:3901, negotiating handshake... 2025-05-26T14:37:13.373409Z INFO garage_net::netapp: Connection established to 1911db8ef49ad7a9 ==== HEALTHY NODES ==== ID Hostname Address Tags Zone Capacity DataAvail 1911db8ef49ad7a9 garage 192.168.147.2:3901 NO ROLE ASSIGNED |
And create a layout, which should than be visible in the WebUI
|
1 2 3 4 |
docker exec -ti garage /garage layout assign -z dc1 -c 1G 1911db8ef49ad7a9 docker exec -ti garage /garage layout apply --version 1 |
Testdrive
Connect via awscli. Create ~/.aws/credentials
|
1 2 3 4 5 |
[default] aws_access_key_id=xxxx aws_secret_access_key=xxxx |
Next ~/.aws/config
|
1 2 3 4 5 |
[default] region=garage endpoint_url=https://api.bucket.your-domain.net |
Connect to a bucket you created
|
1 2 3 |
aws s3 ls s3://test --endpoint-url https://api.bucket.your-domain.net |
Security Best Practices
Secret Management: Never use default or predictable secrets in production. Generate cryptographically secure tokens:
|
1 2 3 4 5 6 7 |
# RPC Secret (64-character hex) openssl rand -hex 32 # Admin and Metrics Tokens (base64) openssl rand -base64 32 |
Network Security: Consider running Garage behind a reverse proxy (nginx, Caddy, Traefik) for SSL termination and additional security headers.
Access Control: Implement proper bucket policies and IAM-style permissions through Garage’s key management system.
Operational Excellence
Initial Cluster Setup
Once your Docker Compose stack is running, you’ll need to bootstrap the cluster:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
# 1. Verify Garage is running docker-compose exec garage /garage status # 2. Create cluster layout (single node example) NODE_ID=$(docker-compose exec garage /garage status | grep -o '^[a-f0-9]*') docker-compose exec garage /garage layout assign -z datacenter1 -c 100G $NODE_ID docker-compose exec garage /garage layout apply --version 1 # 3. Create your first bucket docker-compose exec garage /garage bucket create production-data # 4. Generate API credentials docker-compose exec garage /garage key create application-key # 5. Grant bucket access docker-compose exec garage /garage bucket allow \ --read --write --owner \ production-data \ --key application-key |
Monitoring and Maintenance
Garage provides comprehensive metrics through its admin API. Key metrics to monitor include:
- Storage utilization across nodes and zones
- Replication health and consistency status
- Request latency and error rates
- Network partition detection and recovery
Scaling Strategies
One of Garage’s greatest strengths is its ability to scale horizontally. Adding nodes to an existing cluster involves:
- Deploying new nodes with identical configuration (different node IDs)
- Updating the cluster layout to include new nodes
- Rebalancing data distribution across the expanded cluster
The process is designed to be non-disruptive, with data migration happening automatically in the background.
Real-World Applications
Case Study: Media Platform Migration
Consider a typical migration scenario: moving from AWS S3 to self-hosted Garage for a media-heavy application. The process demonstrates Garage’s practical benefits:
Before: Monthly S3 costs of $200+ for 2TB of video content with moderate access patterns.
After: One-time hardware investment of $800 for a three-node Garage cluster providing 6TB usable storage with built-in redundancy.
Migration Process:
- Deploy Garage cluster in parallel with existing S3 setup
- Use
rcloneto migrate data with checksum verification - Update application configuration to point to Garage endpoints
- Gradually shift traffic while monitoring performance
Results: 90% cost reduction, improved data sovereignty, and better performance due to local deployment.
Integration Ecosystem
Garage’s S3 compatibility opens doors to countless integration opportunities:
Development Workflows:
- Docker registries for container image storage
- Git LFS for large file versioning
- Terraform state backends for infrastructure as code
Content Management:
- WordPress media libraries
- Nextcloud external storage
- Static site generators for Jekyll, Hugo, or Gatsby
Backup and Archival:
- restic repositories for encrypted backups
- Duplicity for incremental backups
- Personal media libraries with automatic organization
The Future of Garage
Funding and Development Trajectory
Garage’s development roadmap is backed by substantial European Union funding through 2025, ensuring continued innovation and stability. Recent funding rounds have supported:
- Performance optimizations for large-scale deployments
- Enhanced S3 compatibility for edge cases and new API features
- Operational tooling improvements for easier cluster management
- Security enhancements including encryption at rest and improved access controls
Community and Ecosystem
The project benefits from an active community of system administrators, developers, and privacy advocates. Key community initiatives include:
- Integration guides for popular self-hosted applications
- Performance benchmarks across different hardware configurations
- Deployment automation through Ansible, Terraform, and Kubernetes operators
- Monitoring solutions with Prometheus and Grafana dashboards
Conclusion: Why Garage Matters
In a world increasingly dominated by centralized cloud services, Garage represents something profound: the democratization of enterprise-grade storage infrastructure. It proves that sophisticated distributed systems don’t require massive corporate resources or specialized expertise to deploy and maintain.
For individuals and organizations committed to data sovereignty, Garage offers a practical path forward. It’s not just about avoiding vendor lock-in or reducing costs (though it accomplishes both). It’s about reclaiming control over one of your most valuable digital assets: your data.
The storage needs of 2025 demand solutions that are resilient, flexible, and respectful of user autonomy. Garage delivers on all three counts while maintaining the compatibility and reliability expected from production storage systems.
Whether you’re a privacy-conscious individual looking to escape Big Tech’s data collection, a small business seeking cost-effective storage solutions, or an organization with specific compliance requirements, Garage provides a compelling alternative that grows with your needs.
The future of storage is distributed, open-source, and in your control. Garage is leading the way.
Resources and Links
- Official Website: https://garagehq.deuxfleurs.fr/
- Documentation: https://garagehq.deuxfleurs.fr/documentation/
- Source Code: https://git.deuxfleurs.fr/Deuxfleurs/garage
- Docker Hub: https://hub.docker.com/r/dxflrs/garage
- Web UI – https://github.com/khairul169/garage-webui
FAQ
What are the best open source alternatives to Amazon S3 storage?
What is Ceph and why is it popular for S3 storage?
How does SeaweedFS compare to traditional object storage systems?
What are the main advantages of using Storj for object storage?
How do I choose between different open source S3 alternatives?
What hardware requirements do these storage systems have?
Can I migrate from Amazon S3 to open source alternatives easily?
What are the cost implications of switching from S3 to open source storage?
How do I set up a basic Ceph cluster for S3 storage?
- Install Ceph on at least 3 nodes
- Configure monitors (ceph-mon), managers (ceph-mgr), and OSDs (ceph-osd)
- Deploy RADOS Gateway (ceph-rgw) for S3 API
- Create storage pools and configure security
What monitoring and management tools are available for open source storage?
How do these systems handle data backup and disaster recovery?
What security features do open source S3 alternatives provide?
How do I configure S3 API access for these storage systems?
What performance optimizations should I consider?
How do I troubleshoot common issues with open source storage systems?
- Check system logs and health status
- Verify network connectivity between nodes
- Monitor disk space and performance
- Review configuration files
- Test with simple operations first
