# 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`.

The current default by NixOS is `garage_0_8` which is also the latest
major version available.

## 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`.
:::

::: {.warning}
Until 1.0 is released, patch-level upgrades are considered as minor version upgrades.
Minor version upgrades are considered as major version upgrades.
i.e. 0.6 to 0.7 is a major version upgrade.
:::

  - **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.7`, you cannot upgrade to `0.9`.
    You need to upgrade to `0.8` 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.