garage-installer

Garage Cluster Installer

One binary. Two nodes. Zero hassle.

Interactive wizard that deploys a two-node dev/test Garage S3-compatible object storage cluster on Ubuntu/Debian nodes using Docker.

Features

Documentation

📚 Complete Documentation →

Why This Installer?

Why Deno?

Why Docker?

Deployment Model

[Your Machine]
    └── garage-installer binary
        ├── SSH to Node 1
        │   ├── Preflight checks
        │   ├── Docker setup
        │   └── Deploy container
        ├── SSH to Node 2
        │   ├── Preflight checks
        │   ├── Docker setup
        │   └── Deploy container
        └── Configure Cluster
            ├── Connect nodes
            ├── Apply layout
            └── Verify health

Quick Start

NOTE: binaries for the installer aren’t yet available. This practically means that you must pull the source code, make sure that Deno is installed, and run from source. Instructions for installing Deno can be found below in the Development > Prerequisites.

git clone https://github.com/miha42-github/garage-installer.git
cd garage-installer
deno task dev

Download

# Linux
wget https://github.com/miha42-github/garage-installer/releases/latest/download/garage-installer-linux-x64
chmod +x garage-installer-linux-x64

# macOS
wget https://github.com/miha42-github/garage-installer/releases/latest/download/garage-installer-macos-x64
chmod +x garage-installer-macos-x64
# On first run, macOS may block execution. If so, run:
# xattr -d com.apple.quarantine ./garage-installer-macos-x64

# Windows
# Download from: https://github.com/miha42-github/garage-installer/releases/latest/download/garage-installer-windows-x64.exe

macOS Users: If you see “cannot be opened because the developer cannot be verified”, see the macOS Security Warning section in the troubleshooting guide.

Run

WARNING: Not yet available documentation in this section is not correct.

./garage-installer-linux-x64

That’s it! The wizard will guide you through:

  1. Node Discovery - Enter SSH details for both nodes
  2. Connectivity Test - Verify SSH access
  3. Pre-flight Checks - System validation with auto-fix
  4. Configuration - Storage capacity and settings
  5. Deployment - Docker container setup
  6. Cluster Setup - Node connection and layout
  7. Verification - Health checks and endpoint display

Prerequisites

Local Machine (where you run the installer)

Remote Nodes (where Garage will run)

Note: Docker and Docker Compose require manual installation on the remote nodes before running the installer. The installer cannot install them automatically as this requires sudo privileges with interactive password entry. See the Installing Prerequisites section in the troubleshooting guide for detailed instructions.

The installer will automatically:

What Gets Installed

On each node, the installer will:

  1. Download Garage Docker image - dxflrs/garage:v2.1.0 (default, configurable)
  2. Create directory structure: 
    ~/garage/
├── docker-compose.yml
├── garage.toml
└── [Docker volumes for data/metadata]

Docker containers:

Ports used:

Post-Installation

After successful installation, you’ll have access to Garage’s S3 API.

💡 For complete integration examples, see the examples/ directory (AWS CLI and Node.js).

Quick Start with AWS CLI

# Configure (credentials provided by installer)
aws configure set aws_access_key_id YOUR_ACCESS_KEY
aws configure set aws_secret_access_key YOUR_SECRET_KEY
aws configure set default.region garage
aws configure set default.s3.addressing_style path

# Create bucket and upload
aws s3 mb s3://my-bucket --endpoint-url http://NODE_IP:3900
echo "Hello Garage" > test.txt
aws s3 cp test.txt s3://my-bucket/ --endpoint-url http://NODE_IP:3900

📚 See AWS CLI Configuration Guide for complete setup instructions.

Management Commands

# Check cluster status
ssh user@node1 "docker exec garage /garage status"

# View logs
ssh user@node1 "docker logs garage"

# Restart cluster
ssh user@node1 "cd ~/garage && docker compose restart"

📚 For day-2 operations, see the Troubleshooting Guide.

Troubleshooting

Common issues and quick fixes:

SSH Connection Fails

# Check SSH access
ssh user@hostname

# Verify key permissions
chmod 600 ~/.ssh/id_rsa

Docker Permission Denied

# Add user to docker group (requires re-login)
sudo usermod -aG docker $USER

Ports Already in Use

# Find what's using the port
sudo ss -tlnp | grep 3900

Nodes Can’t Reach Each Other

# Test connectivity
ping node2-hostname

# Check firewall (allow port 3901 for RPC)
sudo ufw allow 3901/tcp

📚 For comprehensive troubleshooting, see the Troubleshooting Guide.

Development

Prerequisites

Deno 1.40+ is required to build from source.

Install Deno:

# macOS / Linux
curl -fsSL https://deno.land/install.sh | sh

# Windows (PowerShell)
irm https://deno.land/install.ps1 | iex

# Or via package managers:
# macOS: brew install deno
# Linux: snap install deno
# Windows: choco install deno

See https://deno.land/manual/getting_started/installation for more options.

Run from source

git clone https://github.com/miha42-github/garage-installer.git
cd garage-installer
deno task dev

Build

# Linux binary
deno task compile-linux

# macOS binary
deno task compile-macos

# Windows binary
deno task compile-windows

# All platforms
deno task build-all

Binaries will be in dist/ directory.

Security Considerations

The installer follows security best practices:

Network Security:

Limitations & Use Cases

Two-Node Clusters

When to Use This

When NOT to Use This

What’s Next?

After installing your cluster:

  1. Try it out - Upload and download files with AWS CLI
  2. Integrate - Connect your applications using the Node.js + Express guide
  3. Monitor - Access metrics endpoint on port 3903
  4. Plan ahead - See FUTURES.md for roadmap and upcoming features

📚 See FUTURES.md for the complete development roadmap and planned features.

Support & Community

Credits

Remember: This installer creates a two-node cluster for development and testing. For production, deploy at least 3 nodes in different physical locations for proper fault tolerance.

Garage itself is licensed under AGPLv3.

Credits

Support

Remember: This installer creates a two-node cluster. It’s not production-ready. For production, deploy at least 3 nodes in different physical locations.

But for learning, testing, or development? This is a quick way to get started with Garage.

This site is open source. Improve this page.