How to Install Garage on Debian: S3-Compatible Object Storage

Garage is an S3-compatible, distributed object storage service designed for self-hosting. Built by the Deuxfleurs association, it targets exactly the situation most homelabs and small collectives find themselves in: a handful of modest machines, possibly in different physical locations, that together should provide durable, geo-redundant storage exposed through the familiar Amazon S3 API.

Because Garage speaks the S3 protocol, it slots directly beneath the enormous ecosystem of tools that already know how to talk to S3: backup software, static site deployers, aws s3 and rclone, application SDKs, and more. You point them at your Garage endpoint instead of AWS and keep your data on hardware you own. It is written in Rust, ships as a single static binary, and deliberately avoids heavyweight dependencies.

Garage is not in the official Debian repositories, and although upstream provides static binaries, wiring them into a service and keeping them updated is manual work. The unofficial deb.griffo.io repository provides a prebuilt Garage package that installs with apt and stays current with upstream releases.

Install the Latest Garage on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest Garage .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install garage

The rest of this guide explains what each command does, how to verify the install, how to keep Garage up to date, and what to check when something goes wrong.

What Makes Garage Special?

  • 🪣 S3-compatible API - Works with existing S3 clients, SDKs and tooling out of the box
  • 🌍 Geo-distributed by design - Spread nodes across sites with zone-aware replication
  • 🦀 Single Rust binary - No JVM, no sprawling dependency tree, tiny resource footprint
  • 🔁 Configurable replication - Choose the replication factor that balances durability and cost
  • 🔑 Fine-grained access keys - Per-bucket read/write/owner permissions tied to S3 access keys
  • 🌐 Static website hosting - Serve buckets directly as websites over HTTP
  • 📊 Built-in admin CLI and API - Manage layout, buckets and keys without external tooling
  • ⚖️ Self-healing rebalancing - Data is redistributed automatically as the cluster layout changes

Why Use the deb.griffo.io Repository?

The deb.griffo.io repository makes running Garage on Debian straightforward:

  • Easy installation and updates through the standard APT package manager
  • Automatic dependency management handled by the packaging
  • Always tracks upstream releases so you get new Garage versions promptly
  • No compiling from source and no manual binary juggling
  • Works across supported Debian releases (Bookworm, Trixie and Sid)

Prerequisites

Before you begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (install with sudo apt install curl if needed)
  • A directory with enough disk space for object data

Step 1: Add the deb.griffo.io Repository

Add the repository GPG key and source definition:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each command does:

  1. Keyrings directory: Creates /etc/apt/keyrings with the correct mode to store the key.
  2. GPG key: Downloads and de-armours the signing key so APT can verify package authenticity.
  3. Repository: Adds the source line, letting lsb_release -sc fill in your Debian codename.
  4. Update: Refreshes the package index to expose the new packages.

Step 2: Update the Package List

If you have not already refreshed the index, do it now:

sudo apt update

Step 3: Install Garage

Install Garage with a single command:

sudo apt install garage

APT downloads the latest packaged Garage binary and installs it along with any dependencies.

Step 4: Verify the Installation

Confirm the installation and print the version:

garage --version

You should see output similar to:

garage v1.0.1

Getting Started with Garage

The garage binary is both the server and the administration CLI. The workflow below stands up a single-node cluster, then creates a bucket and an access key you can point S3 tooling at.

Write a Configuration File

Create /etc/garage.toml. A minimal single-node configuration looks like this:

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

replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "REPLACE_WITH_openssl_rand_hex_32"

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

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

Generate the RPC secret with:

openssl rand -hex 32

Start the Server

Run the server (in production, do this from a systemd unit):

sudo garage server

In another terminal, check the cluster status:

garage status

You will see your node listed but marked as having no role yet, because the storage layout has not been assigned.

Assign the Storage Layout

Take the node ID from garage status, assign it a zone and capacity, then apply the new layout version:

# Assign the node to zone "dc1" with 1 TB of capacity
garage layout assign -z dc1 -c 1T <node-id>

# Review the staged layout
garage layout show

# Apply it
garage layout apply --version 1

Create a Bucket and Access Key

With the layout applied, create a bucket and an S3 access key, then grant the key access:

# Create a bucket
garage bucket create photos

# Create an access key
garage key create my-app-key

# Grant the key read and write access to the bucket
garage bucket allow --read --write photos --key my-app-key

# Inspect the result
garage bucket info photos
garage key info my-app-key

The garage key info output shows the Access Key ID and Secret Access Key. Feed those into any S3 client:

aws --endpoint-url http://127.0.0.1:3900 --region garage \
  s3 cp ./cat.jpg s3://photos/cat.jpg

Serve a Bucket as a Website

Garage can expose a bucket over HTTP for static hosting:

garage bucket website --allow photos

Keeping Garage Updated

Since Garage comes from the repository, it updates with the rest of your system:

sudo apt update && sudo apt upgrade

For clusters, upgrade nodes one at a time and read the upstream release notes first, as on-disk metadata formats and configuration keys can change between major versions.

Other Tools from deb.griffo.io

The deb.griffo.io repository packages many other self-hosting and infrastructure tools that complement Garage:

  • Headscale - A self-hosted Tailscale control server for private networking
  • Forgejo - A self-hosted lightweight Git forge
  • DuckDB - An in-process SQL OLAP database, handy for querying data
  • k9s - A terminal UI to interact with your Kubernetes clusters

Troubleshooting

GPG or Key Issues

If APT reports the repository signature cannot be verified, re-add the key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot find the garage package:

  1. Re-run sudo apt update after adding the repository.
  2. Ensure your Debian release is supported (Bookworm, Trixie or Sid).
  3. Check the source file: cat /etc/apt/sources.list.d/deb.griffo.io.list.

Node Shows No Role or Data Is Unavailable

If garage status shows your node without a role, or clients get errors:

  1. Remember that a fresh node has no layout: you must run garage layout assign and garage layout apply before any bucket works.
  2. Confirm rpc_secret is identical on every node, and that openssl rand -hex 32 produced a 64-character value.
  3. Verify metadata_dir and data_dir exist and are writable by the user running the server.

Uninstalling

To remove Garage:

sudo apt remove garage

To also remove the repository definition and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Your stored objects and metadata under /var/lib/garage are not touched by the package removal; delete them manually if you want to reclaim the space.

Conclusion

Garage brings S3-compatible object storage to hardware you own, with geo-aware replication that suits distributed homelabs and small collectives, and the deb.griffo.io repository turns installing it on Debian into a single apt install. A single Rust binary acts as both server and admin CLI, so the whole system stays small and comprehensible.

Once the layout is applied and a bucket exists, Garage behaves like any other S3 endpoint: point your backups, static sites and application SDKs at it and let the cluster handle durability. It is a pragmatic, self-hosted foundation for storage that grows from one node to several without changing how your applications talk to it.

Frequently Asked Questions

How do I install the latest Garage on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install garage. The repository tracks upstream Garage releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for Garage?

Yes. deb.griffo.io publishes Garage as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update Garage to the latest version?

Run sudo apt update && sudo apt upgrade. Once Garage is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install Garage on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install Garage on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Garage project.