Garage: an S3-compatible object store for small geo-distributed clusters

The problem Garage solves: S3 semantics across a few physical sites

Most object stores assume a datacenter. Garage assumes the opposite: a cluster of nodes that are not in the same building, potentially not in the same city. The README describes it as an S3-compatible distributed object storage service "designed for self-hosting at a small-to-medium scale", and it says the design target is clusters "composed of nodes running at different physical locations", so that data is replicated across those locations and the service "stays available even when some servers are unreachable".

The intended user is not a platform team of dozens. It is an operator who has a few machines and wants an S3 endpoint they control. Deuxfleurs, the project's author, is described in the README as "an experimental small-scale self hosted service provider" that has run Garage in production since its first release in 2020. That is a specific claim about who maintains it and why: the software comes out of an organisation that needed this shape of storage itself.

What Garage does not try to be is a general-purpose replacement for a large cloud object store. The README points readers to a goals and use cases page rather than enumerating limits inline, which is a reasonable place to put them but means the README alone will not tell you whether your workload fits.

How the Rust workspace maps to the storage design

The repository is a Cargo workspace, and the member list is the clearest available picture of the architecture. Each internal crate is versioned together at 2.4.1 and covers one layer: garage_db, garage_util, garage_net, garage_rpc, garage_table, garage_block, garage_model, garage_api_common, garage_api_s3, garage_api_k2v, garage_api_admin, garage_web, and the default member src/garage, which produces the binary.

The split tells you where the design effort went. There is a dedicated block crate and a dedicated table crate, so the system separates chunk storage from the metadata that indexes it. There is a net crate and an rpc crate, which matches the geo-distributed premise: nodes have to find each other and coordinate across links that are slower and less reliable than a datacenter fabric. There is a model crate sitting above block and table, which is where the object-level logic would live.

The API surface is also split. garage_api_s3 is the S3-compatible endpoint the README advertises. garage_api_k2v is a second, non-S3 API, and the workspace ships a separate k2v-client crate at 0.0.4 for it. garage_api_admin and garage_web sit alongside them, so there is an administrative interface and a web layer beyond the S3 protocol.

All of this is visible in Cargo.toml. What is not visible there is how the replication actually behaves under partition, and the README does not attempt to explain it. That detail lives in the documentation site.

Installing Garage and starting a node

The README does not contain install instructions. It links to a quick start page and to binary releases, and the repository itself carries a Dockerfile, a flake.nix, a shell.nix and a default.nix, so there are several build paths depending on what you already run.

The Dockerfile is the shortest to read. It is a scratch image that copies the compiled binary to the root and starts the server, with two environment variables set:

FROM scratch

ENV RUST_BACKTRACE=1
ENV RUST_LOG=garage=info

COPY result/bin/garage /
CMD [ "/garage", "server"]

The ENV lines set the default log level to info for the garage module and enable Rust backtraces. The COPY line expects the binary at result/bin/garage, which is a Nix build output path rather than a plain cargo target directory, so this Dockerfile is meant to be fed by the Nix build.

The Makefile shows the local development path instead. Building is a plain cargo build, and a node is started by pointing the binary at a TOML config file:

cargo build
RUST_LOG=garage=debug ./target/debug/garage -c tmp/config1.toml server

The -c flag takes the config path and server is the subcommand. The Makefile also defines run1, run2 and run3 targets with separate config files, which is how a multi-node cluster is exercised locally. The README's quick start page is where the actual config contents are documented; the repository does not ship a sample config.

Where Garage is the wrong choice

The README is explicit that Garage targets small-to-medium scale, and that framing is a real boundary rather than modesty. If your working set is large enough that you would normally reach for a distributed storage system with dedicated metadata servers and a large operations team, the design goals here point elsewhere.

The geo-distribution premise is also a constraint in the other direction. Garage assumes nodes at different physical locations and replicates across them. If all your machines sit in one rack, you are paying for cross-site coordination logic you do not need, and a single-site object store will have a simpler failure model.

There is a documentation gap worth naming. The README has no install steps, no sample configuration, and no upgrade or rollback procedure. It delegates all of that to the website. If you need to evaluate Garage from the repository alone, you cannot: you have to leave the repo and read the quick start, goals and features pages. The README does not document rollback, and it does not state a supported version skew between nodes during an upgrade.

Finally, the project is a mirror. The README labels this repository as a mirror and points to git.deuxfleurs.fr as the main repository, so issues and patches belong there, not on the mirror.

Garage compared with MinIO and Ceph

The obvious comparison is MinIO, which is also S3-compatible and also aimed at self-hosting. The difference in approach is the distribution model. MinIO is generally deployed as a set of nodes that together form one storage pool, and its erasure coding is designed around that pool being reachable. Garage starts from nodes at different physical locations and treats unreachability as an expected condition, which is why its workspace has separate net and rpc crates and a replication design the README describes as keeping the service available when some servers are unreachable. If your nodes are all in one datacenter, MinIO's model is a closer fit to the hardware.

Ceph is the other reference point, and the gap is operational weight. Ceph splits responsibilities across monitors, managers, OSDs and metadata servers, and it is built for scale that Garage does not claim. Garage compiles to a single binary, as the Dockerfile shows with its one COPY line and a CMD of garage server. That is a different trade: fewer moving parts, and a smaller envelope of workloads it is intended for.

The non-S3 API is a third axis. Garage ships garage_api_k2v and a k2v-client crate, so it offers a second access protocol alongside S3. Neither MinIO nor Ceph exposes that particular interface, and the README does not describe what k2v is for, so treat it as something to investigate on the documentation site rather than a reason to pick Garage on its own.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-20. That is the only maintenance signal available here; the README describes production use since 2020, and the Cargo.toml pins the internal crates at 2.4.1, which indicates a versioned release line rather than an unversioned trunk.

Upgrade cost is the part the README does not answer. It does not document rollback, and it does not describe how nodes of different versions behave during a rolling upgrade. For a geo-distributed cluster that is the question that matters most, because you will be upgrading nodes one at a time across links you do not fully control. The documentation site is the place to look, and if it is silent too, that is a gap to weigh before you commit.

The licence is AGPL-3.0, stated in the README as "entirely free software released under the terms of the AGPLv3". The practical consequence is that the AGPL's network clause applies to software offered to users over a network. If you run Garage only as internal storage, that distinction may not matter to you. If you build a service on top of it and expose that service to third parties, the obligations are different, and that is a question for your own legal review rather than something this article can settle.

Editorial conclusion

Garage fits operators running a small number of machines in different places who want S3 semantics without a large storage team, and who are willing to read the quick start and goals pages rather than the README alone. It is the wrong tool if you need one big single-site cluster with a managed control plane, or if you want a vendor to handle upgrades. Before adopting it, check the goals and features pages against your replication and availability needs, read the AGPLv3 licence text, and confirm which binary release or build path matches your platform.

Frequently asked questions

Official sources

1. deuxfleurs-org/garage on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README