Skip to content
Klutch.sh Docs

Deploying Garage

Introduction

Garage is an S3-compatible distributed object storage service designed for self-hosting at a small-to-medium scale. Built with Rust, Garage is lightweight, efficient, and capable of running on modest hardware including ARM devices like Raspberry Pi while consuming minimal CPU and RAM resources.

Garage is designed for storage clusters composed of nodes running at different physical locations, providing a storage service that replicates data across locations and remains available even when some servers are unreachable. This makes it ideal for home labs, small businesses, and edge deployments.

Key highlights of Garage:

  • S3-Compatible API: Drop-in replacement for Amazon S3, compatible with existing S3 tools and libraries
  • Lightweight Design: Runs efficiently on minimal hardware, perfect for edge deployments
  • Distributed Architecture: Built for multi-node clusters with geographic distribution
  • Data Replication: Automatic replication across nodes for data durability
  • High Availability: Continues operating even when some nodes are offline
  • Web Hosting: Serve static websites directly from buckets
  • Admin API: RESTful API for bucket and key management
  • Multi-tenancy: Support for multiple users and access keys
  • Open Source: Licensed under AGPL-3.0

This guide walks through deploying Garage on Klutch.sh using Docker, configuring persistent storage, and setting up the service for production use.

Why Deploy Garage on Klutch.sh

Deploying Garage on Klutch.sh provides several advantages for your object storage needs:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Garage without complex orchestration or manual server configuration. Push to GitHub, and your storage service deploys automatically.

Persistent Storage: Attach persistent volumes for your data and metadata. Your objects survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your storage API and any hosted static websites.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync with your repository.

Scalable Resources: Allocate CPU, memory, and storage based on your needs. Start small and scale up as your storage requirements grow.

Environment Variable Management: Securely store sensitive configuration through Klutch.sh’s environment variable system without exposing credentials in your repository.

Custom Domains: Assign a custom domain to your Garage instance for branded storage URLs and static website hosting.

Always-On Availability: Your object storage remains accessible 24/7 without managing your own hardware.

Prerequisites

Before deploying Garage on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Garage configuration
  • Basic familiarity with Docker and containerization concepts
  • Understanding of S3 concepts (buckets, keys, objects)
  • (Optional) A custom domain for your Garage instance

Understanding Garage Architecture

Garage is built on a distributed architecture designed for reliability:

Rust Core: The application is written in Rust, providing memory safety, performance, and low resource consumption.

Data Storage: Objects are stored in a configurable data directory, with automatic chunking and deduplication.

Metadata Storage: A separate metadata directory stores bucket configurations, object listings, and cluster state using an embedded database.

S3 API Gateway: The S3-compatible API handles standard S3 operations like PUT, GET, DELETE, and listing.

Admin API: A separate API endpoint for administrative operations like creating buckets and access keys.

Cluster Coordination: Nodes communicate using a gossip protocol for cluster membership and data routing.

Preparing Your Repository

To deploy Garage on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

garage-deploy/
├── Dockerfile
├── garage.toml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM dxflrs/garage:v1.0.1


# Copy configuration file
COPY garage.toml /etc/garage.toml


# Create data directories
RUN mkdir -p /var/lib/garage/meta /var/lib/garage/data


# Expose ports
# S3 API
EXPOSE 3900
# Admin API
EXPOSE 3903
# RPC port for cluster communication
EXPOSE 3901


# Start Garage
CMD ["garage", "-c", "/etc/garage.toml", "server"]

Creating the Configuration File

Create a garage.toml configuration file:

# Garage configuration file


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


db_engine = "lmdb"


replication_factor = 1


[rpc]
bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
secret_file = "/var/lib/garage/meta/rpc_secret"


[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"


[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"


[admin]
api_bind_addr = "[::]:3903"
admin_token_file = "/var/lib/garage/meta/admin_token"

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Garage can be configured through the configuration file and environment variables:

VariableRequiredDefaultDescription
GARAGE_ALLOW_WORLD_READABLE_SECRETSNofalseAllow world-readable secret files
GARAGE_ADMIN_TOKENConditional-Admin API token (can use file instead)
GARAGE_RPC_SECRETConditional-RPC secret for cluster communication

Deploying Garage on Klutch.sh

Once your repository is prepared, follow these steps to deploy Garage:

    Generate Security Secrets

    Before deployment, generate the required secrets:

    Terminal window
    # Generate RPC secret (for cluster communication)
    openssl rand -hex 32 > rpc_secret
    

    # Generate admin token
    openssl rand -hex 32 > admin_token

    Save these values securely—you’ll need them for configuration.

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile garage.toml .dockerignore README.md
    git commit -m "Initial Garage deployment configuration"
    git remote add origin https://github.com/yourusername/garage-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “garage” or “object-storage”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Garage Dockerfile.

    Configure HTTP Traffic

    Garage serves its S3 API over HTTP. In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 3900 (S3 API port)

    Attach Persistent Volumes

    Persistent storage is essential for Garage. Add the following volumes:

    Mount PathRecommended SizePurpose
    /var/lib/garage/meta5 GBMetadata and cluster state
    /var/lib/garage/data100+ GBObject data (adjust based on needs)

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Garage container
    • Provision an HTTPS certificate

    Initialize the Cluster

    After deployment, you need to initialize the Garage cluster. Access your container and run:

    Terminal window
    # Get node ID
    garage status
    

    # Configure the node (replace with your values)
    garage layout assign <NODE_ID> -z dc1 -c 1G -t node1
    

    # Apply the layout
    garage layout apply --version 1

    Create Access Credentials

    Create an access key for using the S3 API:

    Terminal window
    # Create a new key
    garage key create my-key
    

    # Note the Access Key ID and Secret Access Key

    Create a Bucket

    Create your first storage bucket:

    Terminal window
    # Create a bucket
    garage bucket create my-bucket
    

    # Allow the key to access the bucket
    garage bucket allow --read --write my-bucket --key my-key

    Access Garage

    Your Garage S3 API is now available at https://your-app-name.klutch.sh. Use any S3-compatible client or library to interact with your storage.

Using Garage with S3 Clients

AWS CLI Configuration

Configure the AWS CLI to use your Garage instance:

Terminal window
aws configure
# AWS Access Key ID: Your Garage access key
# AWS Secret Access Key: Your Garage secret key
# Default region name: garage
# Default output format: json

Use with the --endpoint-url flag:

Terminal window
# List buckets
aws --endpoint-url https://your-app-name.klutch.sh s3 ls


# Upload a file
aws --endpoint-url https://your-app-name.klutch.sh s3 cp file.txt s3://my-bucket/


# Download a file
aws --endpoint-url https://your-app-name.klutch.sh s3 cp s3://my-bucket/file.txt ./

Python boto3

Use Garage with Python’s boto3 library:

import boto3


s3 = boto3.client(
    's3',
    endpoint_url='https://your-app-name.klutch.sh',
    aws_access_key_id='YOUR_ACCESS_KEY',
    aws_secret_access_key='YOUR_SECRET_KEY',
    region_name='garage'
)


# List buckets
response = s3.list_buckets()
for bucket in response['Buckets']:
    print(bucket['Name'])


# Upload file
s3.upload_file('file.txt', 'my-bucket', 'file.txt')

rclone Configuration

Configure rclone for Garage:

[garage]
type = s3
provider = Other
access_key_id = YOUR_ACCESS_KEY
secret_access_key = YOUR_SECRET_KEY
endpoint = https://your-app-name.klutch.sh

Use rclone commands:

Terminal window
# List buckets
rclone lsd garage:


# Sync directory to bucket
rclone sync ./local-dir garage:my-bucket/

Static Website Hosting

Garage can serve static websites directly from buckets.

Enabling Website Hosting

Configure a bucket for website hosting:

Terminal window
# Enable website hosting
garage bucket website --allow my-bucket

Uploading Website Files

Upload your static website:

Terminal window
# Upload website files
aws --endpoint-url https://your-app-name.klutch.sh s3 sync ./website s3://my-bucket/


# Set index.html as default
aws --endpoint-url https://your-app-name.klutch.sh s3 website s3://my-bucket/ --index-document index.html

Administration

Managing Keys

Terminal window
# List all keys
garage key list


# Show key details
garage key info my-key


# Delete a key
garage key delete my-key

Managing Buckets

Terminal window
# List all buckets
garage bucket list


# Show bucket details
garage bucket info my-bucket


# Delete a bucket
garage bucket delete my-bucket

Monitoring

Check cluster status:

Terminal window
# View cluster status
garage status


# View bucket statistics
garage bucket info --statistics my-bucket

Production Best Practices

Security Recommendations

  • Secure Secrets: Keep your admin token and RPC secret secure
  • Access Keys: Create separate keys for different applications
  • Bucket Policies: Use bucket policies to restrict access
  • HTTPS: Always use HTTPS (provided by Klutch.sh)
  • Regular Rotation: Rotate access keys periodically

Storage Planning

  • Capacity: Plan storage based on expected data growth
  • Replication: Consider replication factor for data durability
  • Quotas: Set bucket quotas to prevent runaway usage

Backup Strategy

Protect your data:

  1. Cross-bucket Replication: Replicate critical data to another bucket
  2. Metadata Backups: Back up the metadata directory
  3. Export Important Data: Regularly export critical objects

Troubleshooting Common Issues

S3 API Errors

Symptoms: Clients receive error responses.

Solutions:

  • Verify access key credentials
  • Check bucket permissions
  • Ensure endpoint URL is correct
  • Review Garage logs for details

Application Won’t Start

Symptoms: Container exits immediately.

Solutions:

  • Verify configuration file syntax
  • Check that data directories are writable
  • Ensure ports are not conflicting
  • Review startup logs

Upload Failures

Symptoms: Large uploads fail or timeout.

Solutions:

  • Check available storage space
  • Verify network connectivity
  • Increase timeout settings in clients
  • Check for resource constraints

Additional Resources

Conclusion

Deploying Garage on Klutch.sh gives you a lightweight, S3-compatible object storage service with automatic builds, persistent storage, and secure HTTPS access. The combination of Garage’s efficient design and Klutch.sh’s deployment simplicity means you can have your own cloud storage running in minutes.

Whether you’re backing up files, hosting static websites, or providing storage for applications, Garage on Klutch.sh provides a reliable, self-hosted alternative to commercial cloud storage services. With S3 compatibility, you can use familiar tools and libraries while maintaining full control over your data.