Home • Explore • Blog • Models • CI
☰



nixpkgs
1st chunk of `nixos/modules/services/web-servers/garage.md`
20a67fd4e77ba4672899c9499010f7e277070f4e55088be60000000100000978
# Garage {#module-services-garage}

[Garage](https://garagehq.deuxfleurs.fr/)
is an open-source, self-hostable S3 store, simpler than MinIO, for geodistributed stores.
The server setup can be automated using
[services.garage](#opt-services.garage.enable). A
 client configured to your local Garage instance is available in
 the global environment as `garage-manage`.

## General considerations on upgrades {#module-services-garage-upgrade-scenarios}

Garage provides a cookbook documentation on how to upgrade:
<https://garagehq.deuxfleurs.fr/documentation/cookbook/upgrading/>

::: {.warning}
Garage has two types of upgrades: patch-level upgrades and minor/major version upgrades.

In all cases, you should read the changelog and ideally test the upgrade on a staging cluster.

Checking the health of your cluster can be achieved using `garage-manage repair`.
:::

  - **Straightforward upgrades (patch-level upgrades).**
    Upgrades must be performed one by one, i.e. for each node, stop it, upgrade it : change [stateVersion](#opt-system.stateVersion) or [services.garage.package](#opt-services.garage.package), restart it if it was not already by switching.
  - **Multiple version upgrades.**
    Garage do not provide any guarantee on moving more than one major-version forward.
    E.g., if you're on `0.9`, you cannot upgrade to `2.0`.
    You need to upgrade to `1.2` first.
    As long as [stateVersion](#opt-system.stateVersion) is declared properly,
    this is enforced automatically. The module will issue a warning to remind the user to upgrade to latest
    Garage *after* that deploy.

## Advanced upgrades (minor/major version upgrades) {#module-services-garage-advanced-upgrades}

Here are some baseline instructions to handle advanced upgrades in Garage, when in doubt, please refer to upstream instructions.

  - Disable API and web access to Garage.
  - Perform `garage-manage repair --all-nodes --yes tables` and `garage-manage repair --all-nodes --yes blocks`.
  - Verify the resulting logs and check that data is synced properly between all nodes.
    If you have time, do additional checks (`scrub`, `block_refs`, etc.).
  - Check if queues are empty by `garage-manage stats` or through monitoring tools.
  - Run `systemctl stop garage` to stop the actual Garage version.
  - Backup the metadata folder of ALL your nodes, e.g. for a metadata directory (the default one) in `/var/lib/garage/meta`,
Title: Garage S3 Store: Overview and Upgrade Procedures
Summary
This document introduces Garage, an open-source, self-hostable S3-compatible object storage for geo-distributed deployments, simpler than MinIO, with `garage-manage` for client operations. It then details Garage upgrade procedures, differentiating between patch-level and minor/major versions. Key advice: consult the official cookbook, read changelogs, test upgrades on staging clusters, and use `garage-manage repair` for health checks. Patch-level upgrades are straightforward, performed node-by-node. Advanced (minor/major) upgrades require specific steps: disable API/web access, run `garage-manage repair` extensively (tables, blocks), verify data sync, check queues, stop the Garage service, and back up metadata across all nodes. Direct upgrades skipping major versions are unsupported, requiring intermediate upgrades.