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

---
# nuzlocke-tracker-he1n
title: Add local GoTrue container for dev auth testing
status: todo
type: feature
priority: normal
created_at: 2026-03-20T20:57:04Z
updated_at: 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

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