Self-Hosted S3 Mastery: Building a Lightweight Storage Stack with Garage & Docker

📂

Production Deployment Blueprint: The complete self-hosted stack configuration, automated volume architectures, and network orchestration assets can be verified directly on GitHub: mg3994/s3-garage

Introduction: The Case for Garage S3

In the cloud ecosystem, object storage landscapes are heavily dominated by heavyweight platforms like MinIO or enterprise-grade AWS S3 clusters. However, for decentralized edge computing, private self-hosted setups, and high-efficiency personal "Command Centers," these platforms introduce steep runtime and memory penalties.

Garage (v2.2.0) cuts through this overhead. Written entirely in Rust, it provides a lightweight, resilient object storage alternative engineered directly for geo-distributed bare-metal arrays and isolated single-node environments. By abandoning complex consensus layers in favor of a CRDT-based synchronization model (Conflict-Free Replicated Data Types) and pairing it with a high-speed SQLite metadata engine, Garage delivers raw, low-overhead disk-based persistence that can be safely backed up and migrated with zero friction.

1. Technical Breakdown (garage.toml)

The garage.toml configuration serves as the strict system source of truth for the storage daemon. It manages everything from the micro-internal RPC node pipeline parameters to the public-facing S3 API endpoints.

🔒

Security Architecture Rule: The rpc_secret must be a robust, 64-character hex string. While a static token is assigned for this local environment mapping, always provision internet-facing production containers using uniquely generated hashes derived via openssl rand -hex 32.

etc/garage.toml

TOML

# Garage Core Persistence System Layout
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1

# RPC Topology: Node-to-node internal cluster fabric
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "f79edbcc2062a3d0d8202b19bd0b0e7b0a0e5e04381f8e7c04cfdb82dd0c7f9c"

# S3 Gateway Configuration
[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

# Static Website Hosting Subsystem
[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

# Administrative Engineering Endpoint
[admin]
api_bind_addr = "[::]:3903"
admin_token = "dev-admin-secret-123"

Decoupling the Internal Network Pipeline

The inclusion of the [s3_web] directive unlocks native, high-performance static site hosting directly out of the cluster. By simply creating a target bucket and mapping an index.html payload, Garage works dual shifts—acting as a robust object repository and an ultra-lean public web server.

2. Orchestration via Docker Compose

To ensure identical runtime environments across cross-platform instances (Windows, Linux, and macOS), the architecture is containerized using Docker Compose. A lightweight graphical interface layer is linked alongside the engine using Garage-WebUI.

docker-compose.yml

YAML

services:
  garage:
    image: dxflrs/garage:v2.2.0
    container_name: garage
    restart: always
    ports:
      - "3900-3904:3900-3904"
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./meta:/var/lib/garage/meta
      - ./data:/var/lib/garage/data

  webui:
    image: khairul169/garage-webui:latest
    container_name: garage-webui
    environment:
      - API_BASE_URL=http://garage:3903
      - API_ADMIN_KEY=dev-admin-secret-123
      - S3_ENDPOINT_URL=http://garage:3900
    depends_on:
      - garage

Notice the explicit assignment of the Read-Only (:ro) flag on the garage.toml volume mount. This prevents the runtime container engine from mutating the host configuration parameters, keeping container tracking entirely stateless and reproducible across initializations.

3. Endpoint Architecture & Matrix Layout

Garage handles data isolation by splitting operational administrative planes away from consumer APIs. The interface ports map to the local stack boundaries as follows:

Port	Endpoint Subtype	Functional Domain Responsibility
3900	S3 API	Main data gateway for client SDK integrations (AWS-CLI, Boto3, Rclone).
3902	S3 Web	Direct HTTP payload delivery channel tailored for static web deployments.
3903	Admin API	Privileged operations endpoint handling bucket policies and key rings.
3904	Dashboard	WebUI management layer interface for localized visual administration.

4. Step-by-Step Implementation Flow

To transition this distributed stack out of documentation and into an active running state, execute the following implementation flow step by step:

• Sync Workspace Assets: Pull down the environment configuration maps from the s3-garage repository.
• Initialize Persistence Directories: Manually spin up the local storage directories using your host shell. This steps around Docker root ownership and namespace permission collision limits:

Terminal

Bash

mkdir meta data && docker-compose up -d

• Bootstrap Administration Keyrings: Launch your local browser interface and target http://localhost:3904. Input your configured admin_token to authenticate, enter the workspace control dashboard, and issue your primary S3 cryptographic access credentials.
• Validate Endpoints: Configure a target profile in your local AWS toolchain or script runner, override the default service location parameter to target http://localhost:3900, and execute a sample object validation push.

By stripping away runtime overhead and database heavy-lifting, Garage v2.2.0 yields a clean, high-performance, and deeply robust blueprint for localized object storage clusters. Deploy smart, and keep your data self-hosted.