Migrating Longhorn Backup from MinIO to Garage

MinIO discontinued their Docker images and moved to a source-only distribution model, leaving many homelab installs running outdated versions with known CVEs. Garage is a self-hosted, S3-compatible distributed object storage service — lightweight, actively maintained, and a clean drop-in replacement for Longhorn backups.

Note

For restoring from Longhorn backups after this migration, see Restoring from Longhorn Backups. The process is identical regardless of whether you’re using MinIO or Garage.

Prerequisites: Ubuntu server with Docker and Docker Compose, Kubernetes cluster with Longhorn installed.

Setting Up Garage

Directory and Secrets

sudo mkdir -p /srv/docker/garage/{meta,data}
cd /srv/docker/garage

# Generate RPC secret
openssl rand -hex 32

# Generate admin token
openssl rand -hex 32

`/srv/docker/garage/garage.toml`

1
metadata_dir = "/var/lib/garage/meta"
2
data_dir = "/var/lib/garage/data"
3
db_engine = "lmdb"
4

5
replication_factor = 1
6

7
rpc_bind_addr = "0.0.0.0:3901"
8
rpc_public_addr = "127.0.0.1:3901"
9
rpc_secret = "YOUR_RPC_SECRET_HERE"
10

11
[s3_api]
12
s3_region = "us-east-1"
13
api_bind_addr = "0.0.0.0:3900"
14
root_domain = ".s3.garage"
15

16
[admin]
17
api_bind_addr = "0.0.0.0:3903"
18
admin_token = "YOUR_ADMIN_TOKEN_HERE"

Tip

replication_factor = 1 is fine for single-node. Use 3 for multi-node redundancy.

`/srv/docker/garage/docker-compose.yml`

1
version: "3"
2
services:
3
  garage:
4
    image: dxflrs/garage:v2.1.0
5
    container_name: garage
6
    network_mode: "host"
7
    restart: unless-stopped
8
    volumes:
9
      - ./garage.toml:/etc/garage.toml
10
      - ./meta:/var/lib/garage/meta
11
      - ./data:/var/lib/garage/data
12

13
  webui:
14
    image: khairul169/garage-webui:latest
15
    container_name: garage-webui
16
    restart: unless-stopped
17
    volumes:
18
      - ./garage.toml:/etc/garage.toml:ro
19
    environment:
20
      API_BASE_URL: "http://127.0.0.1:3903"
21
      S3_ENDPOINT_URL: "http://127.0.0.1:3900"
22
    network_mode: "host"

docker-compose up -d

Configure Storage

alias garage="docker exec -ti garage /garage"

garage node id

# Assign storage capacity
garage layout assign <node-id> -z default -c 100G

garage layout show
garage layout apply --version 1

# Create bucket and key
garage bucket create longhorn
garage key create longhorn-key
garage bucket allow longhorn --read --write --owner --key longhorn-key

# Note the Key ID and Secret key
garage key info longhorn-key --show-secret

Integrate with Longhorn

Kubernetes Secret

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: minio-secret
5
  namespace: longhorn-system
6
type: Opaque
7
stringData:
8
  AWS_ACCESS_KEY_ID: <Key-ID-from-garage>
9
  AWS_SECRET_ACCESS_KEY: <Secret-Key-from-garage>
10
  AWS_ENDPOINTS: http://<GARAGE_SERVER_IP>:3900
11
  AWS_REGION: us-east-1

kubectl apply -f minio-secret.yaml

HelmRelease Update

1
---
2
apiVersion: source.toolkit.fluxcd.io/v1
3
kind: HelmRepository
4
metadata:
5
  name: longhorn
6
  namespace: longhorn-system
7
spec:
8
  interval: 1h
9
  url: https://charts.longhorn.io
10
---
11
apiVersion: helm.toolkit.fluxcd.io/v2
12
kind: HelmRelease
13
metadata:
14
  name: longhorn
15
spec:
16
  interval: 1h
17
  chart:
18
    spec:
19
      chart: longhorn
20
      version: 1.10.0
21
      sourceRef:
22
        kind: HelmRepository
23
        name: longhorn
24
        namespace: longhorn-system
25
  values:
26
    defaultSettings:
27
      backupTarget: "s3://longhorn@us-east-1/"
28
      backupTargetCredentialSecret: "minio-secret"
29
      backupstorePollInterval: "300"

Warning

In Longhorn 1.10.0+, backup settings are under defaultSettings, not a separate defaultBackupStore section.

Verify

Access the Garage WebUI at http://<SERVER_IP>:3909. Then test a backup from Longhorn UI → Volume → Create Backup and confirm it appears in the longhorn bucket.

garage bucket list
garage bucket info longhorn

Troubleshooting

WebUI “Unknown Error” — confirm the [admin] section is in garage.toml and restart:

docker-compose restart
docker logs garage

Port 3903 connection refused:

netstat -tlnp | grep 3903

Longhorn can’t reach Garage:

kubectl run -it --rm debug --image=amazon/aws-cli --restart=Never -- \
  s3 ls s3://longhorn --endpoint-url http://<GARAGE_IP>:3900

Migrating Longhorn Backup from MinIO to Garage

Setting Up Garage

Directory and Secrets

`/srv/docker/garage/garage.toml`

`/srv/docker/garage/docker-compose.yml`

Configure Storage

Integrate with Longhorn

Kubernetes Secret

HelmRelease Update

Verify

Troubleshooting

Resources

Share this post

Related Posts

Synology HyperBackup to Oracle Cloud

Restoring from Longhorn Backups

Safeguarding My Critical Data