AGENTS.md

Repository role

Docker Compose orchestration for the crearte full stack. Three repos must stay siblings:

repos/
├── crearte/          # frontend (build context for web-* images)
├── crearte-server/   # backend Go API (build context for api-* images)
└── crearte-deploy/   # this repo — compose only, no app code

Everything runs in containers. Do not introduce host-run workflows (no npm run dev / go run on the host) in docs, scripts, or compose.

Safety Rules

Branch naming: {feat|fix|docs|chore}/{branch-name} (e.g. fix/compose-port-clash).
Before git commit: run git branch --show-current. If on master, do NOT commit — ask the user for a branch name, create it, and commit there.
.env is gitignored and must stay that way. Never commit secrets. Any new secret must land in .env.example as an empty placeholder (with a comment) in the same commit that introduces it.
Changes → docs/CHANGELOG.md (this repo is not under web/, so CHANGELOG_webui.md never applies). Higher versions on top.
CHANGELOG entry format: same entry has English line then Chinese line on consecutive lines (no blank line between them); different entries are separated by a blank line.
Merging into master: always create a merge commit — git merge --no-ff <branch> (never fast-forward, the integration point must be recorded). Delete the merged branch afterwards.
Compose changes that alter usage must update README.md in the same commit.

Compose invariants (breaking these loses data or breaks the stack)

Sibling layout: build contexts are ../crearte and ../crearte-server. Never repoint them or inline copies of the app code.
dev and prod both publish host port 8080 — the profiles are mutually exclusive. Keep it that way unless README is updated accordingly.
Volume names are data identity: renaming a volume orphans its data. Never rename pgdata-*, bundle-keys-*, minio-data-*, or the *_node_modules volumes.
db-test (pgdata-test, 127.0.0.1:5432) is the integration-test database and is truncated freely. Never point TEST_DATABASE_URL at dev data — db-debug shares the pgdata-dev volume with db-dev, so a misdirected test run wipes development data.
Never run docker compose ... down -v unless the user explicitly asks: it destroys postgres data, bundle keys, and MinIO objects, and the MinIO bucket init must then be redone by hand.
Required secrets use ${VAR:?…} so compose fails fast when missing. Keep the :? guard and .env.example in sync for every new secret.
The one-time MinIO bucket init (mc mb local/crearte + anonymous download) exists because the volume is empty on first creation — do not silently automate it away; document any change in README.
Keep depends_on health gating (api waits for service_healthy db); removing it makes first-boot races routine.

Verification (required before claiming a compose change works)

docker compose config -q for each touched profile (--profile dev|prod|debug|mock).
docker compose --profile <p> up -d --build, then docker compose ps — healthchecks must pass.
Smoke-test the affected path (e.g. docker compose exec api-dev wget -qO- http://127.0.0.1:8080/healthz, or the upload flow through http://localhost:8080).
Tear down with plain down (never -v) unless the task is specifically about destroying data.

Layout notes

docs/superpowers/ (plans/specs) is tracked in this repo — unlike in crearte, where it is gitignored.
No app code, no tests, no build scripts live here; those belong to crearte / crearte-server.

3.6 KiB Raw Blame History