Hands-on Lab

Migrate MinIO to Garage step by step with rclone

October 21, 2026 3 min

0 / 7

Cheat sheet

Found it useful? Don't miss the next lab

The video has captions and a transcript. Everything it shows is written out, step by step, below. Cheat sheet with every command

0:00 / 0:00

We create a Compose project in /srv/minio with a test MinIO: the cgr.dev/chainguard/minio:latest image, the only tag on Chainguard's free tier. First we hand the data folder to user 65532 with chown, because the image does not run as root, and we generate the password with openssl inside the container.

mkdir -p /srv/minio/data && chown 65532:65532 /srv/minio/data && cd /srv/minio
printf 'MINIO_ROOT_USER=minioadmin\nMINIO_ROOT_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env
cat > docker-compose.yml <<'EOF'
services:
  minio:
    image: cgr.dev/chainguard/minio:latest
    command: ["server", "/data"]
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - "9000:9000"
    volumes:
      - ./data:/data
EOF
docker compose up -d --quiet-pull minio

I did it

We wait for the /minio/health/live endpoint to answer and check the result: HTTP 200. stat confirms the data folder belongs to user 65532, the one the Chainguard image uses.

for i in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9000/minio/health/live)" = 200 ] && break; sleep 2; done
echo "minio health: HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9000/minio/health/live)"
stat -c 'data owner uid: %u' /srv/minio/data

What this proves

minio health: HTTP 200 the MinIO health endpoint answers 200 Goal · you have a running source to copy the data from
data owner uid: 65532 the data folder belongs to user 65532 Goal · you avoid the Chainguard image's file access denied error

We generate 200 JSON documents and 100 random files of 4 to 32 KB, create the app-data bucket and upload them with mc mirror from the cgr.dev/chainguard/minio-client image. Then we create the appminio01 user, with an openssl secret, and attach the readwrite policy: it plays the part of your application's credentials.

mkdir -p /srv/seed/docs /srv/seed/bin
for i in $(seq 1 200); do printf '{"id":%d,"title":"doc %d"}\n' $i $i > /srv/seed/docs/doc-$i.json; done
for i in $(seq 1 100); do head -c $((4096 * (1 + i % 8))) /dev/urandom > /srv/seed/bin/blob-$i.bin; done
cd /srv/minio && set -a && . ./.env && set +a
printf 'APP_KEY=appminio01\nAPP_SECRET=%s\n' "$(openssl rand -hex 20)" > app.env && . ./app.env
mc() { docker run --rm --network minio_default -e MC_HOST_old="http://$MINIO_ROOT_USER:$MINIO_ROOT_PASSWORD@minio:9000" -v /srv/seed:/seed:ro cgr.dev/chainguard/minio-client:latest "$@"; }
docker pull -q cgr.dev/chainguard/minio-client:latest >/dev/null
mc mb old/app-data && mc mirror /seed old/app-data | tail -n 4
mc admin user add old "$APP_KEY" "$APP_SECRET" && mc admin policy attach old readwrite --user "$APP_KEY"

I did it

We count the bucket with mc du, connecting with the appminio01 key instead of the admin one: app-data holds 300 objects and the application can see them.

cd /srv/minio && . ./app.env
docker run --rm --network minio_default -e MC_HOST_app="http://$APP_KEY:$APP_SECRET@minio:9000" cgr.dev/chainguard/minio-client:latest du app/app-data

What this proves

300 objects mc du counts 300 objects in app-data Goal · you know the exact figure that has to reach Garage
the query ran with the appminio01 key, not the admin one Goal · you know that key works in MinIO before you take it to Garage

We write the guide's garage.toml: LMDB metadata and data under /var/lib/garage, replication_factor = 1 and s3_region = "us-east-1", the region MinIO clients already use. Both secrets come from openssl into .env, and the garage service starts from dxflrs/garage:v2.4.1 with --single-node, which builds the node layout with no manual steps.

mkdir -p /srv/minio/garage/meta /srv/minio/garage/data && cd /srv/minio
cat > garage.toml <<'EOF'
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "us-east-1"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
EOF
cat >> .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -base64 32)
EOF
cat >> docker-compose.yml <<'EOF'
  garage:
    image: dxflrs/garage:v2.4.1
    command: ["/garage", "server", "--single-node"]
    restart: unless-stopped
    environment:
      GARAGE_RPC_SECRET: ${GARAGE_RPC_SECRET}
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
    ports:
      - "3900:3900"
      - "3902:3902"
      - "127.0.0.1:3903:3903"
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./garage/meta:/var/lib/garage/meta
      - ./garage/data:/var/lib/garage/data
EOF
docker compose up -d --quiet-pull garage

I did it

We wait until garage health reports a healthy cluster. The single node is up and all 256 partitions have quorum, so there is no need to assign the layout by hand with garage layout.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
for i in $(seq 1 60); do garage health 2>/dev/null | grep -qE 'Cluster health: +HEALTHY' && break; sleep 2; done
garage health

What this proves

HEALTHY garage health reports Cluster health: HEALTHY Goal · Garage accepts writes before you copy anything
Partitions with quorum: 256 all 256 partitions have quorum Goal · you confirm --single-node already created the cluster layout

Garage has no root user: each key gets permissions bucket by bucket. We create the migracion key, save its secret to garage-key.txt without printing it, create the app-data bucket with the same name as in MinIO and grant it --read, --write and --owner.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage key create migracion > garage-key.txt && grep -E 'Key ID|Key name' garage-key.txt
garage bucket create app-data >/dev/null
garage bucket allow --read --write --owner app-data --key migracion >/dev/null

I did it

garage bucket info confirms the app-data global alias, 0 objects so far and the migracion key with RWO permissions: read, write and owner.

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage bucket info app-data | grep -E 'Global alias|Objects|Permissions|RWO'

What this proves

RWO the migracion key has read, write and owner on app-data Goal · rclone will be able to write to the bucket with that key
app-data the bucket is named app-data, the same as in MinIO Goal · object paths stay the same after the migration

rclone.conf declares minio with provider = Minio and garage with provider = Other, region = us-east-1 and force_path_style = true, filling in the keys from .env and garage-key.txt. rclone/rclone:1.75.1 joins the minio_default network and syncs app-data; --metadata keeps the headers and --fast-list cuts the listing calls.

cd /srv/minio && set -a && . ./.env && set +a
cat > rclone.conf <<EOF
[minio]
type = s3
provider = Minio
access_key_id = $MINIO_ROOT_USER
secret_access_key = $MINIO_ROOT_PASSWORD
endpoint = http://minio:9000

[garage]
type = s3
provider = Other
access_key_id = $(awk '/Key ID/ {print $3}' garage-key.txt)
secret_access_key = $(awk '/Secret key/ {print $3}' garage-key.txt)
region = us-east-1
endpoint = http://garage:3900
force_path_style = true
EOF
docker pull -q rclone/rclone:1.75.1 >/dev/null
docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 sync minio:app-data garage:app-data --metadata --fast-list --transfers 8 --checkers 16 -v 2>&1 | grep -v 'Copied (new)'

I did it

rclone check with --download fetches every object from MinIO and from Garage and compares the content, not just the size or the ETag. It ends with 0 differences and 300 matching files: the copy is complete.

cd /srv/minio && docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 check minio:app-data garage:app-data --download --fast-list --checkers 16

What this proves

0 differences found rclone found no object that differs or is missing between MinIO and Garage Goal · you can switch MinIO off knowing Garage holds the same data
300 matching files all 300 objects match byte for byte Goal · the figure matches the 300 objects we counted in MinIO

We stop MinIO with docker compose stop, keeping its data. Then garage key import --yes accepts the appminio01 key even though it does not start with GK: it meets the minimums of 8 characters for the ID and 16 for the secret. Finally, garage bucket allow grants it read and write on app-data.

cd /srv/minio && . ./app.env && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
docker compose stop minio
garage key import --yes -n app-antigua "$APP_KEY" "$APP_SECRET" | grep -E 'Key ID|Key name'
garage bucket allow --read --write app-data --key app-antigua | grep app-antigua

I did it

docker compose ps confirms MinIO is stopped. With the appminio01 key pointed at garage:3900, mc du counts the 300 objects and mc cat reads a document: an application only has to change the address.

cd /srv/minio && . ./app.env
docker compose ps -a minio --format '{{.Service}}: {{.State}}'
mc() { docker run --rm --network minio_default -e MC_HOST_app="http://$APP_KEY:$APP_SECRET@garage:3900" cgr.dev/chainguard/minio-client:latest "$@"; }
mc du app/app-data && mc cat app/app-data/docs/doc-7.json

What this proves

minio: exited the MinIO container is stopped Goal · you know the next reads cannot come from MinIO
300 objects the MinIO key sees the 300 objects in Garage Goal · your applications keep working on switchover day without touching their credentials
"title":"doc 7" mc cat returns the content of doc-7.json from Garage Goal · you check a real read, not just a listing

We remove the project with docker compose down -v, which deletes the MinIO and Garage containers and the minio_default network. Then we delete /srv/minio and /srv/seed, with the data, the keys and rclone.conf.

cd /srv/minio && docker compose down -v && cd / && rm -rf /srv/minio /srv/seed

I did it

We count what is left: 0 containers, 0 minio_default networks and 0 files in /srv. The machine is back where it started.

echo "containers left: $(docker ps -aq | wc -l)"; echo "networks left: $(docker network ls -q --filter name=minio_default | wc -l)"; ls -A /srv | wc -l | sed 's/^/files left in \/srv: /'

What this proves

containers left: 0 no container is left Goal · you leave the machine as it was before the lab

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Video transcript

0:00 From MinIO to Garage, with 0 differences.
0:04 We start the source MinIO with the Chainguard image, because minio/minio no
0:10 longer pulls from Docker Hub.
0:11 The Chainguard image runs MinIO as user 65532,
0:18 so the data folder must belong to it.
0:20 We move a MinIO bucket to Garage and prove not a single object is missing.
0:26 Garage is a lightweight S3 server, written in Rust, that replaces MinIO for storing
0:32 files and backups.
0:33 MinIO with data, Garage beside it, an rclone copy, a check and the key switch.
0:39 We check it:
0:40 the MinIO health check answers 200 and the data folder belongs to user 65532.
0:48 We load 300 objects into the app-data bucket with mc and create the key an
0:53 application would use.
0:56 We check it with the application's key:
0:58 the app-data bucket holds 300 objects in MinIO.
1:04 With --single-node, Garage builds the cluster layout itself on first start.
1:09 We add Garage v2.4.1 to the same Compose project, with a single node and the
1:15 us-east-1 region.
1:17 We check it with garage health:
1:19 the cluster is HEALTHY and all 256 partitions have quorum.
1:27 We create the migracion key and the app-data bucket, and grant it read, write
1:32 and owner permissions.
1:33 We check it:
1:34 app-data exists, it is empty and the migracion key has RWO permissions.
1:43 rclone reads from MinIO and writes to Garage over the Compose network, without
1:48 touching the local disk.
1:50 We write rclone.conf with both endpoints and copy with rclone sync:
1:56 300 of 300 transferred.
1:58 We verify it with rclone check, downloading both sides:
2:01 0 differences and 300 matching files.
2:07 We stop MinIO and import the application's key into Garage, so it keeps working
2:12 without changing its credentials.
2:14 We check it:
2:15 with MinIO stopped, the same key reads the 300 objects from Garage on port
2:21 3900.
2:24 We clean up:
2:25 docker compose down removes both containers and the network, and we delete
2:29 the lab folders.
2:32 We check it:
2:33 no containers, no network and no lab files are left.

What this lab does

This lab reproduces, in a throwaway environment, the guide to migrating from MinIO to Garage with Docker. We start from a MinIO with the app-data bucket and 300 objects, bring up Garage v2.4.1 in the same Compose project, copy with rclone 1.75.1 and check the result with rclone check --download: 0 differences and 300 matching files.

The source MinIO uses cgr.dev/chainguard/minio, because minio/minio no longer pulls from Docker Hub. If you ran into that error, the pull access denied for minio/minio guide covers the alternatives. The Chainguard image runs as user 65532 and only publishes latest on its free tier.

How Garage is configured for the migration

The lab’s garage.toml follows the Garage quick start with two changes: the us-east-1 region, which MinIO clients already use, and the data under /var/lib/garage. The secrets are generated with openssl into a .env file, as in the Docker secrets management lab. The --single-node option creates the cluster layout on first start, so garage health already shows a healthy cluster.

Copy, verification and key switch

rclone copies from one S3 server to the other over the Compose network, using the provider = Other template from the Garage client documentation. Verifying with rclone check and --download compares the content of each object, not just its ETag. Finally we stop MinIO and import the application’s key into Garage with garage key import --yes: the same key reads the 300 objects from port 3900.

Garage has no versioning, object lock or bucket policies; the written guide details what you lose and when it is not a fit. If you would rather keep those features, see the MinIO to RustFS migration. And before any migration, keep a copy of the data as in the Docker volume backup lab.

FAQ

Do you need to configure the cluster layout in Garage v2.4.1?

Not with a single node. Since v2.3.0, garage server –single-node creates the layout on first start and keeps it on later starts. In the lab, garage health shows the cluster HEALTHY and all 256 partitions with quorum without running garage layout.

Why use rclone check with –download?

Because without –download rclone compares size and MD5 sum, and objects uploaded in parts have an ETag that is not the MD5 of the content. With –download it fetches both sides and compares the bytes; in the lab it ends with 0 differences and 300 matching files.

Can my applications keep using their MinIO keys on Garage?

Yes, with garage key import –yes, as long as the ID has at least 8 characters and the secret at least 16. Then grant permissions with garage bucket allow. Use it as a bridge for switchover day and rotate those keys later.

Which S3 region should I set in Garage when migrating from MinIO?

The one your clients already use. MinIO with no region configured accepts almost any, but Garage only accepts its s3_region. This lab uses us-east-1 in garage.toml and in rclone.conf so they match.

Cheat sheet

mkdir -p /srv/minio/data && chown 65532:65532 /srv/minio/data && cd /srv/minio
printf 'MINIO_ROOT_USER=minioadmin\nMINIO_ROOT_PASSWORD=%s\n' "$(openssl rand -hex 16)" > .env
cat > docker-compose.yml <<'EOF'
services:
  minio:
    image: cgr.dev/chainguard/minio:latest
    command: ["server", "/data"]
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - "9000:9000"
    volumes:
      - ./data:/data
EOF
docker compose up -d --quiet-pull minio

mkdir -p /srv/seed/docs /srv/seed/bin
for i in $(seq 1 200); do printf '{"id":%d,"title":"doc %d"}\n' $i $i > /srv/seed/docs/doc-$i.json; done
for i in $(seq 1 100); do head -c $((4096 * (1 + i % 8))) /dev/urandom > /srv/seed/bin/blob-$i.bin; done
cd /srv/minio && set -a && . ./.env && set +a
printf 'APP_KEY=appminio01\nAPP_SECRET=%s\n' "$(openssl rand -hex 20)" > app.env && . ./app.env
mc() { docker run --rm --network minio_default -e MC_HOST_old="http://$MINIO_ROOT_USER:$MINIO_ROOT_PASSWORD@minio:9000" -v /srv/seed:/seed:ro cgr.dev/chainguard/minio-client:latest "$@"; }
docker pull -q cgr.dev/chainguard/minio-client:latest >/dev/null
mc mb old/app-data && mc mirror /seed old/app-data | tail -n 4
mc admin user add old "$APP_KEY" "$APP_SECRET" && mc admin policy attach old readwrite --user "$APP_KEY"

mkdir -p /srv/minio/garage/meta /srv/minio/garage/data && cd /srv/minio
cat > garage.toml <<'EOF'
metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_auto_snapshot_interval = "6h"
replication_factor = 1
rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "us-east-1"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
EOF
cat >> .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -base64 32)
EOF
cat >> docker-compose.yml <<'EOF'
  garage:
    image: dxflrs/garage:v2.4.1
    command: ["/garage", "server", "--single-node"]
    restart: unless-stopped
    environment:
      GARAGE_RPC_SECRET: ${GARAGE_RPC_SECRET}
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
    ports:
      - "3900:3900"
      - "3902:3902"
      - "127.0.0.1:3903:3903"
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - ./garage/meta:/var/lib/garage/meta
      - ./garage/data:/var/lib/garage/data
EOF
docker compose up -d --quiet-pull garage

cd /srv/minio && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
garage key create migracion > garage-key.txt && grep -E 'Key ID|Key name' garage-key.txt
garage bucket create app-data >/dev/null
garage bucket allow --read --write --owner app-data --key migracion >/dev/null

cd /srv/minio && set -a && . ./.env && set +a
cat > rclone.conf <<EOF
[minio]
type = s3
provider = Minio
access_key_id = $MINIO_ROOT_USER
secret_access_key = $MINIO_ROOT_PASSWORD
endpoint = http://minio:9000

[garage]
type = s3
provider = Other
access_key_id = $(awk '/Key ID/ {print $3}' garage-key.txt)
secret_access_key = $(awk '/Secret key/ {print $3}' garage-key.txt)
region = us-east-1
endpoint = http://garage:3900
force_path_style = true
EOF
docker pull -q rclone/rclone:1.75.1 >/dev/null
docker run --rm --network minio_default -v "$PWD/rclone.conf:/config/rclone/rclone.conf:ro" rclone/rclone:1.75.1 sync minio:app-data garage:app-data --metadata --fast-list --transfers 8 --checkers 16 -v 2>&1 | grep -v 'Copied (new)'

cd /srv/minio && . ./app.env && garage() { docker compose exec -T -e RUST_LOG=warn garage /garage "$@"; }
docker compose stop minio
garage key import --yes -n app-antigua "$APP_KEY" "$APP_SECRET" | grep -E 'Key ID|Key name'
garage bucket allow --read --write app-data --key app-antigua | grep app-antigua

cd /srv/minio && docker compose down -v && cd / && rm -rf /srv/minio /srv/seed

Found it useful? Don't miss the next lab

Subscribe to the newsletter

What this lab does

How Garage is configured for the migration

Copy, verification and key switch

FAQ

Do you need to configure the cluster layout in Garage v2.4.1?

Why use rclone check with –download?

Can my applications keep using their MinIO keys on Garage?

Which S3 region should I set in Garage when migrating from MinIO?

Cheat sheet