From 40f4a875dcd047324e46e4af53fd2532d660c0df Mon Sep 17 00:00:00 2001 From: PhilippTheServer Date: Fri, 25 Sep 2026 10:16:32 +0200 Subject: [PATCH] docs: document Garage instead of MinIO as the object store Closes #15 Co-Authored-By: Claude Opus 5.5 (1M context) --- API/Architecture.md | 4 ++-- Configuration.md | 14 ++++++++------ Deployment.md | 16 ++++++++-------- Getting-Started.md | 7 ++++--- Orders-and-Fulfillment.md | 4 ++-- home.md | 12 ++++++------ 6 files changed, 30 insertions(+), 27 deletions(-) diff --git a/API/Architecture.md b/API/Architecture.md index e5dc4fe..e1d71f0 100644 --- a/API/Architecture.md +++ b/API/Architecture.md @@ -2,7 +2,7 @@ title: API Architecture description: Endpoint reference, response envelope and error model published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: api, architecture, endpoints, reference editor: markdown dateCreated: 2025-11-19T20:13:35.465Z @@ -69,7 +69,7 @@ controls the shop. | `DELETE` | `/v1/items/{item_uuid}` | Delete item | admin | | `PUT` | `/v1/items/{item_uuid}/image` | Upload the product image | admin | -Product images are held in MinIO, not in the database. Uploads are capped by +Product images are held in the S3-compatible object store, not in the database. Uploads are capped by `STORAGE_MAX_IMAGE_BYTES` (5 MB by default) so a single oversized file cannot fill the object store. diff --git a/Configuration.md b/Configuration.md index 0635081..d2f0f3f 100644 --- a/Configuration.md +++ b/Configuration.md @@ -2,7 +2,7 @@ title: Configuration description: Environment-based configuration management published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: configuration, settings, environment, docker, kubernetes editor: markdown dateCreated: 2025-12-07T09:15:00.000Z @@ -196,7 +196,7 @@ The wiring is defensive throughout: an absent or misconfigured collector produce and a running API. Observability that can cause the outage it exists to diagnose is a bad trade. -## Object storage — MinIO / S3 +## Object storage — S3-compatible | Setting | Default | Description | |---|---|---| @@ -206,11 +206,13 @@ trade. | `STORAGE_BUCKET_ITEMS` | `item-images` | Product images | | `STORAGE_BUCKET_LABELS` | `shipping-labels` | Carrier label files | | `STORAGE_MAX_IMAGE_BYTES` | `5242880` | Largest accepted product image (5 MB) | -| `STORAGE_REGION` | `us-east-1` | Ignored by MinIO, required by the client | +| `STORAGE_REGION` | `us-east-1` | Must match the store's region | -`MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD` configure the MinIO container itself in the -development compose file; the API authenticates with `STORAGE_ACCESS_KEY` and -`STORAGE_SECRET_KEY`, which default to the same values. +The development compose file runs [Garage](https://garagehq.deuxfleurs.fr). On start it +creates its access key from `STORAGE_ACCESS_KEY` and `STORAGE_SECRET_KEY`, so the API and +the store always agree; the API creates its buckets itself. Garage also needs +`GARAGE_RPC_SECRET` (32 random bytes, `openssl rand -hex 32`) — compose refuses to start +without it. Its region is `s3_region` in `docker/garage/garage.toml`, set to `us-east-1`. ## Carrier — DHL diff --git a/Deployment.md b/Deployment.md index 4daa9fb..342a3fb 100644 --- a/Deployment.md +++ b/Deployment.md @@ -2,7 +2,7 @@ title: Production Deployment description: Guide for deploying OpenTaberna to production published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: deployment, docker, production, setup editor: markdown dateCreated: 2025-12-06T15:46:53.723Z @@ -23,18 +23,18 @@ dateCreated: 2025-12-06T15:46:53.723Z Read this before planning a deployment. `docker-compose.dev.yml` starts the **whole world** — API, worker, PostgreSQL, Redis, -Keycloak, MinIO and a Stripe listener. It is a development convenience and is not suitable +Keycloak, Garage and a Stripe listener. It is a development convenience and is not suitable for production: it binds the database and Redis to host ports, relaxes Keycloak's TLS requirement, and stores data in bind-mounted directories next to the checkout. `docker-compose.yml`, the production file, ships **only the API container**, attached to an -external `frontproxy_fnet` network. It assumes PostgreSQL, Redis, Keycloak, MinIO and the +external `frontproxy_fnet` network. It assumes PostgreSQL, Redis, Keycloak, an S3-compatible object store and the worker already exist and are reachable — it does not create them. So a production deployment is: 1. Provision the backing services yourself — managed PostgreSQL and Redis, a Keycloak - instance, S3 or MinIO. + instance, and an S3-compatible object store (Garage, Ceph RGW or AWS S3). 2. Run the worker. It is the same image as the API with a different command (`python -m app.worker_main app.worker.WorkerSettings`) and **it is not optional** — without it, no carrier label is ever created and no reservation ever expires. @@ -50,7 +50,7 @@ Internet ├── yourdomain.com → Reverse proxy → Storefront └── admin.yourdomain.com → Reverse proxy → Admin UI │ - PostgreSQL · Redis · MinIO + PostgreSQL · Redis · S3 │ Worker (same image, own command) ``` @@ -228,9 +228,9 @@ chmod +x /opt/opentaberna/backup.sh 0 2 * * * /opt/opentaberna/backup.sh ``` -**Back up the object store too.** Carrier labels and product images live in MinIO, not in -PostgreSQL, so a database-only backup restores orders whose labels have vanished. Use -`mc mirror` or your provider's replication. +**Back up the object store too.** Carrier labels and product images live in the object store, +not in PostgreSQL, so a database-only backup restores orders whose labels have vanished. +Use an S3 sync tool such as `rclone sync` or your provider's replication. Restore: diff --git a/Getting-Started.md b/Getting-Started.md index 5ee98b6..71570c6 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -2,7 +2,7 @@ title: Getting Started description: Quick start guide for OpenTaberna published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: getting-started, quickstart, setup editor: markdown dateCreated: 2025-12-06T15:30:00.000Z @@ -39,6 +39,7 @@ Everything below assumes you are in one of those directories. ```bash cd fastapi cp .env.example .env +sed -i.bak "s/^GARAGE_RPC_SECRET=$/GARAGE_RPC_SECRET=$(openssl rand -hex 32)/" .env && rm .env.bak docker compose -f docker-compose.dev.yml up -d ``` @@ -50,7 +51,7 @@ That brings up seven containers: | `opentaberna-db` | PostgreSQL 17 | 5432 | | `opentaberna-redis` | Redis 8 — cache and job queue | 6379 | | `opentaberna-keycloak` | Keycloak 26 — identity provider | 8080 | -| `opentaberna-minio` | MinIO — product images, carrier labels | 9000 (S3), 9001 (console) | +| `opentaberna-garage` | Garage (S3-compatible) — product images, carrier labels | 9000 (S3), 3903 (admin/health) | | `opentaberna-worker` | ARQ background worker | — | | `opentaberna-stripe-listener` | Stripe CLI, forwards test webhooks to the API | — | @@ -139,7 +140,7 @@ The Keycloak admin console is at **http://localhost:8080** (`admin` / `admin`). | **Storefront** | http://localhost:4300 | | **Admin UI** | http://localhost:4200 | | **Keycloak** | http://localhost:8080 | -| **MinIO console** | http://localhost:9001 | +| **Garage health** | http://localhost:3903/health | ## Your first API call diff --git a/Orders-and-Fulfillment.md b/Orders-and-Fulfillment.md index 6cd1c76..8b1d565 100644 --- a/Orders-and-Fulfillment.md +++ b/Orders-and-Fulfillment.md @@ -2,7 +2,7 @@ title: Orders and Fulfillment description: The order lifecycle from cart to delivery, and how it survives failure published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: orders, payments, fulfillment, shipping, returns, inventory editor: markdown dateCreated: 2026-08-26T12:00:00.000Z @@ -174,7 +174,7 @@ Label creation goes through a `CarrierAdapter` interface, with two implementatio Manual is not a stub. Shipping by hand is a legitimate way to run a small shop, and it is the path that works before any carrier account exists. -Label files live in MinIO (`STORAGE_BUCKET_LABELS`); the database stores a URL. +Label files live in the object store (`STORAGE_BUCKET_LABELS`); the database stores a URL. ## What the back office does diff --git a/home.md b/home.md index 47b14b0..2627349 100644 --- a/home.md +++ b/home.md @@ -2,7 +2,7 @@ title: OpenTaberna description: Landing page to the OpenTaberna Project published: true -date: 2026-08-26T12:00:00.000Z +date: 2026-09-25T12:00:00.000Z tags: landing page, opentaberna, architecture, start editor: markdown dateCreated: 2025-11-19T14:16:40.237Z @@ -52,7 +52,7 @@ graph LR Worker[ARQ Background Worker] DB[(PostgreSQL)] Redis[(Redis)] - Storage[(MinIO Object Storage)] + Storage[(S3 Object Storage)] Keycloak[Keycloak User Management] Stripe[Stripe] DHL[DHL Parcel API] @@ -88,7 +88,7 @@ OpenTaberna is built from these parts: repository and imported on container start, so the whole auth setup is reproducible from a clean checkout. See [Authorization](/Authorization). - **Redis 8** as a cache and as the queue the background worker pulls from. -- **MinIO** (S3-compatible) for product images and carrier label files. +- **S3-compatible object storage** (Garage in development) for product images and carrier label files. Now to the core of the Project: @@ -159,7 +159,7 @@ subgraph DockerHost[Docker Compose Stack] DB[(PostgreSQL :5432)] Redis[(Redis :6379)] - Minio[(MinIO :9000 / :9001)] + Garage[(Garage :9000)] Keycloak[Keycloak :8080] end @@ -174,12 +174,12 @@ AdminUI --> Keycloak API --> DB API --> Redis -API --> Minio +API --> Garage API --> Keycloak Worker --> DB Worker --> Redis -Worker --> Minio +Worker --> Garage StripeCLI --> API ```