nuzlocke-tracker/.beans/nuzlocke-tracker-he1n--add-local-gotrue-container-for-dev-auth-testing.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Add local GoTrue container for dev auth testing	todo	feature	normal	2026-03-20T20:57:04Z	2026-03-20T21:13:18Z

Problem

The current local Docker setup has no auth service — Supabase is only available as a cloud service. This means:

• Auth flows (login, signup, JWT verification) cannot be tested locally
• The frontend's supabase.ts falls back to a stub client (http://localhost:54321) that doesn't actually exist
• Backend tests mock auth entirely via conftest.py fixtures, so integration testing of the full auth flow is impossible

Approach

Add a GoTrue container (Supabase's auth engine) to the local docker-compose.yml. GoTrue is a standalone Go service that provides the same auth API that Supabase cloud exposes. This gives us local email/password auth without needing Discord/Google OAuth providers configured.

Architecture (Option 3):

• Local dev: Own PostgreSQL + GoTrue container → full auth testing
• Production: Own PostgreSQL + Supabase cloud for auth (handles Discord/Google OAuth)

GoTrue will use the existing db PostgreSQL container, creating its own auth schema (separate from the app's tables managed by Alembic).

Files to modify

• docker-compose.yml — add GoTrue service, configure env vars
• .env.example — add GoTrue-specific local defaults
• frontend/src/lib/supabase.ts — point to local GoTrue when in dev mode
• backend/src/app/core/config.py — may need local JWT secret default
• README.md or docs — document local auth setup

Checklist

• Research GoTrue Docker image and required env vars (JWT secret, DB connection, SMTP disabled, etc.)
• Add gotrue service to docker-compose.yml using the existing db container
• Configure GoTrue to use the same PostgreSQL with its own auth schema
• Set local JWT secret (e.g. super-secret-jwt-token-for-local-dev) shared between GoTrue and the backend
• Update .env.example with local GoTrue defaults (SUPABASE_URL=http://localhost:9999, local JWT secret, local anon key)
• Update frontend/src/lib/supabase.ts to use http://localhost:9999 in dev (GoTrue's local port)
• Verify backend JWT verification works with GoTrue-issued tokens (same HS256 + shared secret)
• Test email/password signup and login flow end-to-end locally
• Verify OAuth buttons gracefully handle missing providers in local dev (show disabled state or helpful message)
• Update docker-compose.yml healthcheck for GoTrue readiness
• Document the local auth setup in README or contributing guide

Notes

• GoTrue image: supabase/gotrue (official, regularly updated)
• GoTrue needs: GOTRUE_DB_DATABASE_URL, GOTRUE_JWT_SECRET, GOTRUE_SITE_URL, GOTRUE_EXTERNAL_EMAIL_ENABLED=true, GOTRUE_MAILER_AUTOCONFIRM=true (skip email verification locally)
• The anon key for local dev can be a static JWT signed with the local secret (Supabase docs show how to generate this)
• Production docker-compose.prod.yml is NOT modified — it continues using Supabase cloud via env vars