From 1f55a70096dfeaad50f2cda390ffec7dae70390d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A2u=20Cao?= <raucao@kosmos.org>
Date: Tue, 6 Oct 2026 15:09:45 +0200
Subject: [PATCH] Switch dev object storage from MinIO to Garage

MinIO no longer publishes prebuilt community images (quay.io returns
401, Docker Hub 404), so the dev setup cannot pull the image.

Use a single-node Garage instance instead, which auto-creates the
remotestorage bucket and a dev-key1 access key on first start, and
point liquor-cabinet at it.
---
 AGENTS.md                 |  2 +-
 README.md                 | 26 ++++++++++++++------------
 docker-compose.yml        | 27 ++++++++++++++++-----------
 docker/garage/garage.toml | 14 ++++++++++++++
 4 files changed, 45 insertions(+), 24 deletions(-)
 create mode 100644 docker/garage/garage.toml

diff --git a/AGENTS.md b/AGENTS.md
index 6fe3e30..6bf026e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,7 +7,7 @@ ejabberd, Discourse, Mastodon, remoteStorage, Nostr, LNDHub, and BTCPay.
 ## Development environment
 
 Development runs in Docker Compose — run all commands against the `web` container.
-Start services: `docker compose up` (web, ldap, redis, minio, liquor-cabinet, strfry).
+Start services: `docker compose up` (web, ldap, redis, garage, liquor-cabinet, strfry).
 The `web` service runs `bin/dev` (foreman: Puma + Tailwind CSS watcher) and embeds
 Solid Queue workers (`SOLID_QUEUE_IN_PUMA=true`).
 
diff --git a/README.md b/README.md
index 6739b35..5753f69 100644
--- a/README.md
+++ b/README.md
@@ -93,20 +93,22 @@ generated database files and the first-run marker, then start over:
     rm -f db/*.sqlite3 tmp/.setup-complete
     docker compose up --build
 
-#### Minio / remoteStorage
+#### Garage / remoteStorage
 
-If you want to run remoteStorage accounts locally, you will have to create the
-respective bucket first. With the `minio` container running (run by default
-when using Docker Compose), follow these steps:
+remoteStorage accounts use the `garage` S3-compatible object store. On first
+start, Garage automatically configures a single-node cluster and creates the
+`remotestorage` bucket together with a `dev-key1` access key (secret
+`1234567890123456`), so no manual setup is required.
 
-* `docker compose up web redis minio liquor-cabinet`
-* Head to http://localhost:9001 and log in with user `minioadmin`, password
-  `minioadmin`
-* Create a new bucket called `remotestorage` (or whatever you
-  change the `S3_BUCKET` config to)
-* Create a new key with ID "dev-key" and secret "123456789" (or whatever you
-  change `S3_ACCESS_KEY` and `S3_SECRET_KEY` to). Leave the policy field empty,
-  as it will automatically allow access to the bucket you created.
+If you want to run remoteStorage accounts locally, the `garage` container is
+started by default when using Docker Compose. To run just the remoteStorage
+stack:
+
+* `docker compose up web redis garage liquor-cabinet`
+
+The S3 API is available at http://localhost:3900 (region `garage`). If you want
+to start over with a fresh storage, delete the `garage-data` volume as well as
+the container.
 
 ### Adding npm modules to use with Stimulus controllers
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 467cc45..b5e56c0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -78,17 +78,21 @@ services:
       redis:
         condition: service_started
 
-  minio:
-    image: quay.io/minio/minio:latest
-    command: "server /data --console-address ':9001'"
+  garage:
+    image: dxflrs/garage:v2.4.1
+    command: ["/garage", "server", "--single-node", "--default-bucket"]
     networks:
       - external_network
       - internal_network
     ports:
-      - "9000:9000"
-      - "9001:9001"
+      - "3900:3900"
     volumes:
-      - minio-data:/data
+      - ./docker/garage/garage.toml:/etc/garage.toml:ro
+      - garage-data:/var/lib/garage
+    environment:
+      GARAGE_DEFAULT_ACCESS_KEY: dev-key1
+      GARAGE_DEFAULT_SECRET_KEY: "1234567890123456"
+      GARAGE_DEFAULT_BUCKET: remotestorage
 
   liquor-cabinet:
     image: gitea.kosmos.org/5apps/liquor-cabinet:2.0.0-rc.1
@@ -102,12 +106,13 @@ services:
       REDIS_HOST: redis
       REDIS_PORT: 6379
       REDIS_DB: 1
-      S3_ENDPOINT: http://minio:9000
-      S3_ACCESS_KEY: dev-key
-      S3_SECRET_KEY: 123456789
+      S3_ENDPOINT: http://garage:3900
+      S3_REGION: garage
+      S3_ACCESS_KEY: dev-key1
+      S3_SECRET_KEY: "1234567890123456"
       S3_BUCKET: remotestorage
     depends_on:
-      - minio
+      - garage
       - redis
 
   strfry:
@@ -145,7 +150,7 @@ networks:
 volumes:
   389ds-data:
     driver: local
-  minio-data:
+  garage-data:
     driver: local
   redis-data:
     driver: local
diff --git a/docker/garage/garage.toml b/docker/garage/garage.toml
new file mode 100644
index 0000000..9f6aadd
--- /dev/null
+++ b/docker/garage/garage.toml
@@ -0,0 +1,14 @@
+metadata_dir = "/var/lib/garage/meta"
+data_dir = "/var/lib/garage/data"
+db_engine = "sqlite"
+
+replication_factor = 1
+
+rpc_bind_addr = "[::]:3901"
+rpc_public_addr = "127.0.0.1:3901"
+rpc_secret = "1799bccfd7411eddcf9ebd316bc1f5287ad12a68094e1c6ac6abde7e6feae1ec"
+
+[s3_api]
+s3_region = "garage"
+api_bind_addr = "[::]:3900"
+root_domain = ".s3.garage.localhost"