mc_cars_gmbh_infraestructure/AGENT.md

AGENT.md – Operational notes for working on MC Cars

A compact field guide for anyone (human or AI) making changes to this stack. Skim this first.

---

1. The deployment model

1. Portainer-native. No build: steps. Every service pulls a pre-built image. The web service uses nginx:1.27-alpine with bind-mounted static files.
2. Absolute host paths. All bind mounts point to /mnt/user/appdata/mc-cars/.... Runtime state lives under /mnt/user/appdata/mc-cars/data/.
3. No named volumes. Wiping data means rm -rf /mnt/user/appdata/mc-cars/data/db — not docker volume rm.
4. Secrets live in .env; the .env ships with dev defaults. Any non-local deployment must rotate every key (see §6).
5. External ports are in the 555xx range to avoid collisions on a busy host (55521 Kong, 55530 Studio, 55532 Postgres, 55543 Kong TLS, 55580 web).

---

2. Migration lifecycle

Migrations come in two flavours:

First-boot only (runs iff /mnt/user/appdata/mc-cars/data/db is empty)

• supabase/migrations/00-run-init.sh — wrapper that runs 01-init.sql via psql so we can pre-create Supabase service roles (anon, authenticated, service_role, authenticator, supabase_auth_admin, supabase_storage_admin) that the official images otherwise assume already exist on their supabase/postgres image. We use plain postgres:15-alpine, so we create them ourselves.
• supabase/migrations/01-init.sql — vehicles table, RLS, bucket row, seed demo vehicles.

Postgres' official entrypoint only processes /docker-entrypoint-initdb.d/ on an empty data dir. To re-run: wipe /mnt/user/appdata/mc-cars/data/db.

Post-boot (every time, idempotent)

• supabase/migrations/post-boot.sql — seeds the admin auth.users row with must_change_password=true, creates the vehicle-photos bucket row if missing. Parameterized: psql -v admin_email=... -v admin_password=....
• supabase/migrations/02-leads.sql — leads + customers + RPCs + supabase_realtime publication. Uses create if not exists, create or replace, and do $$ ... $$ with exists-checks so every object is idempotent.

Both are run by the post-init service, which gates on auth.users and storage.buckets being queryable before touching anything.

Adding a new migration:

• If it's schema the app can't start without on a fresh DB → extend 01-init.sql.
• If it's ongoing / idempotent → new file 03-*.sql, mount it in post-init, append one more psql -f line to the entrypoint.

---

3. Roles, RLS, and the mental model

Role	How obtained	Can do
anon	Anon JWT (shipped to browser)	select on active vehicles; insert on leads only
authenticated	JWT from signInWithPassword	Full CRUD on vehicles/leads/customers, execute RPCs
service_role	Service JWT (never in browser)	Bypasses RLS

• Anon cannot read leads. The booking form is fire-and-forget by design. An abuser submitting with a stolen anon key sees only HTTP 201 with no row data.
• RPCs are SECURITY INVOKER. They run as the caller, so auth.uid() returns the actual admin; RLS still applies.
• qualify_lead is idempotent — calling it twice returns the existing customer row instead of raising.

---

4. Realtime wiring

• Postgres command line forces wal_level=logical, max_wal_senders=10, max_replication_slots=10. Without logical, supabase/realtime crash-loops.
• supabase/realtime:v2.30.23 connects as DB_USER=postgres (not supabase_admin). We're on the plain postgres:15-alpine image; the supabase_admin role does not exist.
• SECRET_KEY_BASE must be ≥ 64 chars; the hardcoded value in docker-compose.yml is a dev default — rotate it on real deploys.
• Replica identity full is set on leads/customers/vehicles so updates broadcast the complete row, not just the PK.
• Kong route /realtime/v1/ → http://realtime:4000/socket (websocket upgrade headers handled by Kong's default config).

---

5. Kong traps

• On Windows/WSL2, Docker Desktop's wslrelay intercepts 127.0.0.1:8000. On the production host Kong is exposed on 55521 (container 8000).
• On a busy Unraid/Docker host all MC Cars ports live in the 555xx range to avoid collisions.
• Kong needs KONG_PLUGINS: bundled,request-transformer,cors,key-auth,acl,basic-auth. Omitting acl breaks Studio.
• kong.yml has one consumer per role with acl groups; plugins key-auth + acl gate which apikey (anon vs service_role) can reach which route.

---

6. Password rotation & admin bootstrap

The .env ADMIN_PASSWORD is a one-shot bootstrap seed. On first login:

1. admin.js reads user.user_metadata.must_change_password.
2. If true, the UI shows the "Passwort setzen" screen and refuses to proceed.
3. Submit calls supabase.auth.updateUser({ password, data: { must_change_password: false } }).
4. The frontend also rejects newPassword === loginPassword before sending.

Result: the live admin password differs from .env from the very first session. The .env value is useful only for a brand-new ./data/db.

Password min length is enforced server-side by GOTRUE_PASSWORD_MIN_LENGTH=10.

---

7. Frontend conventions

• Only the anon key leaves the server. frontend/99-config.sh (bind-mounted into the nginx entrypoint dir) writes config.js at container start from $SUPABASE_URL / $SUPABASE_ANON_KEY. The service_role key is not mounted into web.
• The web service uses nginx:1.27-alpine directly (no build:). Static files + nginx.conf + the entrypoint script are bind-mounted read-only. Updating the frontend is git pull + restart the container.
• .gitattributes enforces eol=lf on *.sh files so the entrypoint doesn't break with CRLF on Windows checkouts.
• frontend/app.js (public) creates a Supabase client with persistSession: false — the public site never needs a session.
• frontend/admin.js uses persistSession: true, storageKey: "mccars.auth" and a single realtime channel mccars-admin that subscribes to leads/customers/vehicles.
• app.js writes vehicle_id (uuid) and denormalized vehicle_label ("BMW M3") into the lead at submit time, so the admin UI renders even if the vehicle is later deleted.

---

8. Common failure modes

Symptom	Cause / Fix
auth container restart loop, "role supabase_auth_admin does not exist"	00-run-init.sh didn't run. Wipe /mnt/user/appdata/mc-cars/data/db, retry.
realtime container exits, "wal_level must be logical"	db command: missing wal_level=logical.
502 on /realtime/v1/ through Kong	Missing acl plugin in KONG_PLUGINS, or realtime not listed in kong.yml consumers.
Admin login works but Leads tab is empty	RLS: session is anon instead of authenticated. Check that signInWithPassword succeeded and token is attached to subsequent requests.
Booking form submits but no row appears	anon lacks INSERT grant on public.leads. Check 02-leads.sql ran (see post-init logs).
.sh files reject with \r: command not found	CRLF line endings. dos2unix or re-save as LF.
Port 8000 "connection refused" on Windows	Docker Desktop wslrelay. Use 55521 (production port).

---

9. How to verify a working stack

docker compose ps                                            # all services up (post-init exited 0)
curl http://localhost:55521/rest/v1/vehicles?select=brand -H "apikey: $ANON" # 6 demo cars

In the browser:

1. Open http://<host>:55580, submit the booking form.
2. Open http://<host>:55580/admin.html, log in with .env bootstrap creds.
3. Rotate the password when prompted.
4. The lead you submitted appears in "Aktive Leads" — in real time.
5. Click Qualifizieren. Row disappears from active, a new row appears in Kunden with the lead_id displayed.
6. Open Supabase Studio at http://<host>:55530 and confirm the customers.lead_id FK matches.

---

10. Things explicitly NOT in this stack

• No n8n. Email automation is out of scope here; do it downstream.
• No Google Analytics / Google Reviews widget.
• No "Anmelden/Registrieren" on the public site. Admin access is intentionally unlinked.
• No logflare / analytics.
• No edge-functions container — RPCs live in Postgres.