garage-ware

Self-hosted management console for a Garage HQ S3-compatible storage cluster. One Docker image, one /data volume to back up. It manages a cluster you already run — it does not install one.

Users get self-service S3 access keys, buckets and quotas; admins get cluster status, storage grants, node repairs and a cluster event timeline. Next.js 16 + React 19 over PocketBase (identity, key/bucket mappings, storage claims) and the Garage admin API, proxied server-side so its token never reaches the browser.

Repo: make-ware/garage-ware · Images: dastron/garage-ware (Docker Hub) and ghcr.io/make-ware/garage-ware (GHCR) — both public, same digests, either works.

Quick start

You need a running Garage cluster with a layout applied and an admin token.

With Docker Compose — the recommended path:

git clone https://github.com/make-ware/garage-ware.git
cd garage-ware

cp .env.docker.example .env.docker   # set GARAGE_ADMIN_URL, GARAGE_ADMIN_TOKEN, GARAGE_S3_ENDPOINT
docker compose up -d
docker compose logs garage-ware | grep '\[setup\]'

With plain Docker (docker run) — no checkout needed: download .env.docker.example, save it as .env.docker (that filename, not .env) and fill in the same three values.

docker run -d \
  --name garage-ware \
  --restart unless-stopped \
  -p 8080:80 \
  -v $PWD/data:/data \
  --env-file .env.docker \
  dastron/garage-ware:latest      # or ghcr.io/make-ware/garage-ware:latest

docker logs garage-ware | grep '\[setup\]'

The health check ships in the image, so both paths get it.

The banner prints a URL and a one-time claim token. Open the URL, create your account, paste the token — you are now the administrator, and land on /admin/status.

/admin/status is the answer to "why isn't this working?" It names anything still misconfigured and the fix for each, and when it cannot reach a cluster at all it links to Garage's install docs and to the admin-only config generator, which writes a garage.toml for you to place on each node without ever handling a secret.

Pin a release with dastron/garage-ware:v1.8.3 instead of tracking latest; to build from your checkout, uncomment the build: block in docker-compose.yml. docker/README.md has the full environment reference, SMTP and bucket-CORS setup, and a troubleshooting table.

Admin token

Create one on any Garage node:

garage admin-token create --name garage-ware

For least-privilege scope and hardening, see docs/ARCHITECTURE.md#admin-token-scope.

Before you invite anyone

• Sign-up is closed by default (SIGNUP_MODE); it stays open only while no administrator exists, which is why claiming promptly matters.
• Configure email at /_/#/settings/mail, or invites and password resets silently never arrive.
• A new user has no storage until you grant a claim from Admin → Claims.
• Self-service claiming is off until FEATURE_NODE_CLAIMS / FEATURE_ASSET_CLAIMS are set; until then an admin assigns node owners and imports existing keys and buckets.

Backup

Everything that persists lives under /data — database, uploads, generated superuser password, first-run state. Snapshot it with tar czf backup.tgz -C $PWD data; restore by extracting on the new host and bringing the container up against the same path.

Develop locally

yarn install && yarn setup   # node 20+, yarn 4 via corepack; downloads the PocketBase binary
yarn dev                     # webapp :3000, PocketBase :8090, shared in watch mode

CONTRIBUTING.md covers scripts, adding a collection and the CI order; docs/ARCHITECTURE.md covers why the boundaries are where they are.

Releases

Conventional commits on main drive release-please; merging its release PR tags vX.Y.Z and calls docker-build.yml. That one build pushes each arch by digest to both registries, then assembles a manifest list per registry, so Docker Hub (dastron/garage-ware) and GHCR (ghcr.io/make-ware/garage-ware) serve byte-identical images under matching tags. Pushing to Docker Hub needs the DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repo secrets; GHCR uses the built-in GITHUB_TOKEN. A fork must edit the one hardcoded DOCKERHUB_IMAGE line — a Docker Hub namespace does not follow the git repo.

License

MIT — see LICENSE.