Initial commit

README.md

@@ -0,0 +1,57 @@
+# storage
+
+Postgres + MinIO for asxp.io and any future small services that need a database
+or object storage. Single-host, no clustering. Deploys via Forgejo Actions to
+the same box that runs the apps.
+
+## What's here
+
+- `docker-compose.yml` — `postgres`, `minio`, and one-shot init containers.
+- `init/postgres-init.sh` — idempotent role/DB bootstrap.
+- `init/minio-bootstrap.sh` — idempotent bucket + per-app service account.
+- `.forgejo/workflows/deploy.yaml` — pushes compose + `.env` to the prod host
+  and runs `docker compose up -d`.
+
+## Networking
+
+Two Docker networks:
+
+- `storage` — internal-only; apps join this as an external network to reach
+  `postgres:5432` and `minio:9000`.
+- `traefik` — existing reverse-proxy network. Only MinIO joins it, to expose
+  the S3 API at `https://s3.asxp.io`.
+
+The MinIO console (`:9001`) is **not** exposed externally. To use it, SSH-port-forward:
+
+```sh
+ssh -L 9001:storage-minio:9001 deploy@prod
+# then open http://localhost:9001
+```
+
+## Adding a new app
+
+1. Pick an app name, e.g. `foo`.
+2. Pick a DB password, S3 access key, S3 secret key for it (any random hex).
+3. Add Forgejo secrets `FOO_DB_PASSWORD`, `FOO_S3_ACCESS_KEY`, `FOO_S3_SECRET_KEY`
+   to this repo *and* to the foo repo.
+4. Extend `init/postgres-init.sh` with `ensure_role "foo" ...` and `ensure_db "foo" "foo"`.
+5. Extend `init/minio-bootstrap.sh` with `ensure_bucket "foo-..."`,
+   `write_policy "foo-...-rw" "foo-..."`, `ensure_user ... "foo-...-rw"`.
+6. Pass the new envs through in `docker-compose.yml` and the deploy workflow.
+7. Push.
+
+## State and backups
+
+Two named Docker volumes are stateful:
+
+- `pg_data` (Postgres data dir) — `/var/lib/docker/volumes/storage_pg_data/_data`
+- `minio_data` (S3 object bytes) — `/var/lib/docker/volumes/storage_minio_data/_data`
+
+Server-level backup covers both. If you ever move off whole-server backup,
+the minimum is `pg_dumpall` for Postgres and `mc mirror` for MinIO.
+
+## Secrets
+
+See [`SECRETS.md`](SECRETS.md) for the full list of Forgejo secrets this repo
+needs. Apps that consume storage (asxpio, future) also need the per-app
+credentials added on *their* repo so they can connect.