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

Garage is an S3-compatible, distributed object storage service built for self-hosting. Created by the Deuxfleurs association to run on cheap, heterogeneous machines spread across different locations, it offers durable, replicated storage exposed through the Amazon S3 API. That combination makes it a natural fit for homelabs and small organisations that want cloud-style object storage without a cloud bill.

The S3 compatibility is the key to Garage’s usefulness. Backup tools, static site publishers, rclone, the aws CLI and countless application SDKs already speak S3, so pointing them at a Garage endpoint requires nothing more than a URL and a set of credentials. Under the hood Garage is a single Rust binary with a deliberately small dependency footprint, which keeps it easy to run and reason about.

Ubuntu does not package Garage in its official archives, and while upstream ships static binaries, turning one into a maintained service is manual work. The unofficial deb.griffo.io repository fixes this by publishing a prebuilt Garage package that installs with apt and follows upstream releases.

Install the Latest Garage on Ubuntu: The Short Version

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

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 - Drops in behind the huge ecosystem of existing S3 clients and SDKs
  • 🌍 Geo-distributed by design - Zone-aware replication across nodes in different locations
  • 🦀 Single Rust binary - Minimal footprint, no JVM and no heavy runtime dependencies
  • 🔁 Configurable replication - Tune the replication factor to trade durability against storage cost
  • 🔑 Fine-grained access keys - Per-bucket read, write and owner permissions per S3 key
  • 🌐 Static website hosting - Publish a bucket directly as a website over HTTP
  • 📊 Built-in admin CLI and API - Manage layout, buckets and keys with the same binary
  • ⚖️ Self-healing rebalancing - Automatically redistributes data when the layout changes

Why Use the deb.griffo.io Repository?

Installing Garage on Ubuntu from deb.griffo.io gives you:

  • Easy installation and updates through the APT package manager
  • Automatic dependency management handled by the packaging
  • Always tracks upstream releases so new Garage versions arrive promptly
  • No compiling from source and no manual binary management
  • Works across supported Ubuntu releases with the codename detected automatically

Prerequisites

Before you start, make sure you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (install with sudo apt install curl if needed)
  • A data directory with sufficient free disk space

Step 1: Add the deb.griffo.io Repository

Register the repository key and source on your system:

# 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

A breakdown of the steps:

  1. Keyrings directory: Creates /etc/apt/keyrings with the correct permissions.
  2. GPG key: Downloads and de-armours the signing key for signature verification.
  3. Repository: Adds the source line, with lsb_release -sc inserting your Ubuntu codename such as noble.
  4. Update: Loads the new repository metadata so the packages are visible.

Step 2: Update the Package List

If you skipped the final command above, run it now:

sudo apt update

Step 3: Install Garage

Install the package:

sudo apt install garage

APT fetches the latest packaged Garage binary and installs it with its dependencies.

Step 4: Verify the Installation

Check the installation and version:

garage --version

Expected output:

garage v1.0.1

Getting Started with Garage

The single garage binary serves both as the storage server and the administration CLI. The following steps bring up a one-node cluster on Ubuntu, then create a bucket and an access key ready for S3 clients.

Create the Configuration File

Write /etc/garage.toml with a minimal single-node setup:

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 and paste the result into the file:

openssl rand -hex 32

Launch the Server

Start Garage (for production, wrap this in a systemd service):

sudo garage server

From a second terminal, look at the cluster:

garage status

The node appears without a role, because you have not yet assigned a storage layout.

Assign and Apply the Layout

Copy the node ID from the status output, give it a zone and capacity, then apply the layout version:

# Assign the node to zone "home" with 500 GB of capacity
garage layout assign -z home -c 500G <node-id>

# Check the staged change
garage layout show

# Apply it
garage layout apply --version 1

Create a Bucket and Access Key

Now create a bucket, mint an access key and connect them:

# Create a bucket
garage bucket create backups

# Create an access key
garage key create laptop-backup

# Grant read and write access
garage bucket allow --read --write backups --key laptop-backup

# Review what you created
garage bucket list
garage key info laptop-backup

garage key info reveals the Access Key ID and Secret Access Key. Use them with any S3 tool, for example rclone or the AWS CLI:

aws --endpoint-url http://127.0.0.1:3900 --region garage \
  s3 cp ./backup.tar.gz s3://backups/backup.tar.gz

Publish a Bucket as a Website

To serve a bucket’s contents over HTTP:

garage bucket website --allow backups

Keeping Garage Updated

Because Garage is installed from the repository, it upgrades with everything else:

sudo apt update && sudo apt upgrade

In a multi-node cluster, upgrade one node at a time and read the release notes beforehand, since metadata formats and configuration keys occasionally change across major versions.

Other Tools from deb.griffo.io

The deb.griffo.io repository packages many other self-hosting and data tools that go well with 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 for analytics
  • k9s - A terminal UI to interact with your Kubernetes clusters

Troubleshooting

GPG or Key Issues

If APT cannot verify the repository signature, re-import 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 locate the garage package:

  1. Run sudo apt update again after adding the repository.
  2. Confirm your Ubuntu release is supported (Jammy, Noble or newer).
  3. Inspect the source line: cat /etc/apt/sources.list.d/deb.griffo.io.list.

Buckets Return Errors or the Node Has No Role

If garage status shows a node without a role, or S3 requests fail:

  1. A new node has no layout assigned. Run garage layout assign followed by garage layout apply before expecting buckets to work.
  2. Ensure rpc_secret matches on every node and is a 64-character hex string from openssl rand -hex 32.
  3. Check that metadata_dir and data_dir exist and are writable by the account running the server.

Uninstalling

To remove Garage:

sudo apt remove garage

To also remove the repository configuration:

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

Objects and metadata under /var/lib/garage survive the package removal; delete them by hand if you are done with the data.

Conclusion

Garage delivers S3-compatible object storage on your own Ubuntu machines, with zone-aware replication that suits distributed, low-budget setups, and the deb.griffo.io repository reduces installation to a single apt install. One Rust binary is both the server and the admin CLI, which keeps operations refreshingly simple.

After you assign the layout and create a bucket, Garage behaves like any S3 endpoint your existing tools already understand. Point your backups, static sites and applications at it and let the cluster take care of durability, on infrastructure you fully control.

Frequently Asked Questions

How do I install the latest Garage on Ubuntu?

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 Ubuntu. 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 Debian?

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

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer. 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.