From 73c3d69dba578b5f4bdb49d83d48f4134a7c997d Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sat, 4 Apr 2026 20:40:30 +0200 Subject: [PATCH] docs(15-01): complete Logto Docker infrastructure plan - Create 15-01-SUMMARY.md with execution results - Update STATE.md with phase 15 position and decisions - Update ROADMAP.md with plan progress - Mark AUTH-04 requirement complete --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 26 ++--- .../15-01-SUMMARY.md | 102 ++++++++++++++++++ 4 files changed, 119 insertions(+), 15 deletions(-) create mode 100644 .planning/phases/15-external-authentication/15-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 121fbd8..1623b4e 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -20,7 +20,7 @@ Requirements for this milestone. Each maps to roadmap phases. - [ ] **AUTH-01**: User can register an account via external OIDC auth provider - [ ] **AUTH-02**: User can log in via external auth provider and access their data - [ ] **AUTH-03**: API keys remain functional for programmatic access (MCP, scripts) -- [ ] **AUTH-04**: Auth provider runs self-hosted alongside the application +- [x] **AUTH-04**: Auth provider runs self-hosted alongside the application - [ ] **AUTH-05**: E2E tests authenticate via API keys without depending on the auth provider ### Multi-User Data Model @@ -124,7 +124,7 @@ Which phases cover which requirements. Updated during roadmap creation. | AUTH-01 | Phase 15 | Pending | | AUTH-02 | Phase 15 | Pending | | AUTH-03 | Phase 15 | Pending | -| AUTH-04 | Phase 15 | Pending | +| AUTH-04 | Phase 15 | Complete | | AUTH-05 | Phase 15 | Pending | | MULTI-01 | Phase 16 | Pending | | MULTI-02 | Phase 16 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 2be42f5..e47e91c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -189,7 +189,7 @@ Plans: | 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 | | 13. Setup Impact Preview | v1.3 | 0/2 | Not started | - | | 14. PostgreSQL Migration | v2.0 | 0/? | Not started | - | -| 15. External Authentication | v2.0 | 0/? | Not started | - | +| 15. External Authentication | v2.0 | 1/3 | In Progress| | | 16. Multi-User Data Model | v2.0 | 0/? | Not started | - | | 17. Object Storage | v2.0 | 0/? | Not started | - | | 18. Global Items & Public Profiles | v2.0 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index d9a43f1..53aac0f 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -25,19 +25,19 @@ See: .planning/PROJECT.md (updated 2026-04-03) ## Current Position -Phase: 14 of 18 (PostgreSQL Migration) -Plan: 0 of ? in current phase -Status: Ready to plan -Last activity: 2026-04-03 — v2.0 roadmap created (Phases 14-18) +Phase: 15 of 18 (External Authentication) +Plan: 1 of 3 in current phase +Status: Executing +Last activity: 2026-04-04 — Completed 15-01 (Logto Docker infrastructure + schema cleanup) -Progress: [----------] 0% (v2.0 milestone) +Progress: [=---------] 5% (v2.0 milestone) ## Performance Metrics **Velocity:** -- Total plans completed: 0 (v2.0 milestone) -- Average duration: -- -- Total execution time: -- +- Total plans completed: 1 (v2.0 milestone) +- Average duration: 3min +- Total execution time: 3min *Updated after each plan completion* @@ -45,13 +45,15 @@ Progress: [----------] 0% (v2.0 milestone) ### Decisions -Key decisions made during v2.0 planning: +Key decisions made during v2.0 planning and execution: - Platform pivot: single-user to multi-user with discovery-first approach -- External auth provider (self-hosted, open-source) — Logto vs Authentik OPEN decision +- External auth provider (self-hosted, open-source) — Logto selected (D-01) - SQLite to Postgres migration — required by auth provider and multi-user concurrency - Structured UGC only — ratings and predefined fields, no freeform text until moderation - Separate globalItems table — not a flag on user items table - Single-user SQLite mode diverges at v2.0 boundary +- Logto shares Postgres instance via separate database created by init script +- OIDC_ISSUER derived from LOGTO_ENDPOINT in docker-compose ### Pending Todos @@ -64,6 +66,6 @@ None active. ## Session Continuity -Last session: 2026-04-03 -Stopped at: v2.0 roadmap created with 5 phases (14-18) covering 30 requirements +Last session: 2026-04-04 +Stopped at: Completed 15-01-PLAN.md (Logto Docker infrastructure + schema cleanup) Resume file: None diff --git a/.planning/phases/15-external-authentication/15-01-SUMMARY.md b/.planning/phases/15-external-authentication/15-01-SUMMARY.md new file mode 100644 index 0000000..01b2ad7 --- /dev/null +++ b/.planning/phases/15-external-authentication/15-01-SUMMARY.md @@ -0,0 +1,102 @@ +--- +phase: 15-external-authentication +plan: 01 +subsystem: infra +tags: [logto, oidc, docker-compose, postgres] + +# Dependency graph +requires: + - phase: 14-postgresql-migration + provides: Postgres database and Docker Compose foundation +provides: + - Logto OIDC provider running as Docker Compose service + - Postgres init script for separate Logto database + - OIDC environment variable documentation + - Schema without users/sessions tables (ready for external auth) +affects: [15-02, 15-03, 16-multi-user-data-model] + +# Tech tracking +tech-stack: + added: [logto (svhd/logto Docker image)] + patterns: [multi-database Postgres init via docker-entrypoint-initdb.d, OIDC env var convention] + +key-files: + created: + - docker-compose.yml + - docker-compose.dev.yml + - docker/init-logto-db.sql + - .env.example + modified: + - src/db/schema.ts + +key-decisions: + - "Logto shares Postgres instance via separate database created by init script" + - "OIDC_ISSUER derived from LOGTO_ENDPOINT in docker-compose, not separately configured" + +patterns-established: + - "Docker init scripts in docker/ directory mounted to docker-entrypoint-initdb.d" + - "OIDC environment variables: LOGTO_ENDPOINT, LOGTO_CLIENT_ID, LOGTO_CLIENT_SECRET, OIDC_AUTH_SECRET" + +requirements-completed: [AUTH-04] + +# Metrics +duration: 3min +completed: 2026-04-04 +--- + +# Phase 15 Plan 01: Logto Docker Infrastructure and Schema Cleanup Summary + +**Logto OIDC provider added to Docker Compose with Postgres init script, users/sessions tables removed from schema** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-04T18:35:52Z +- **Completed:** 2026-04-04T18:38:52Z +- **Tasks:** 2 +- **Files modified:** 6 + +## Accomplishments +- Added Logto as a Docker Compose service in both production and dev configurations with proper health-check dependency on Postgres +- Created Postgres init script that automatically creates the logto database on first boot +- Removed users and sessions tables from GearBox schema, generated Drizzle migration to drop them +- Documented all required OIDC environment variables in .env.example + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add Logto service to Docker Compose and create init script** - `625862f` (feat) +2. **Task 2: Remove users and sessions tables from schema** - `0fe231f` (feat) + +## Files Created/Modified +- `docker-compose.yml` - Production compose with Postgres, Logto, and app services +- `docker-compose.dev.yml` - Dev compose with Postgres and Logto for local auth testing +- `docker/init-logto-db.sql` - SQL script creating separate logto database on Postgres +- `.env.example` - Documents all required environment variables for OIDC configuration +- `src/db/schema.ts` - Removed users and sessions table definitions +- `drizzle/0010_foamy_marvel_zombies.sql` - Migration to drop users and sessions tables + +## Decisions Made +- Logto shares the same Postgres instance but uses a separate database (created by init script), rather than a dedicated Postgres container +- OIDC_ISSUER is derived from LOGTO_ENDPOINT in docker-compose.yml rather than being a separate top-level env var, reducing configuration duplication +- Dev compose uses hardcoded password for Logto DB connection (matching existing dev Postgres pattern) + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None. + +## User Setup Required +None - no external service configuration required. Logto admin console setup (creating OIDC application, obtaining client ID/secret) will be needed before plan 15-02, but is handled as part of the Logto first-boot experience at http://localhost:3002. + +## Next Phase Readiness +- Logto infrastructure is ready for plan 15-02 (server-side OIDC integration) +- Schema is cleaned of old auth tables, ready for OIDC-based authentication +- API keys table preserved for continued programmatic access + +--- +*Phase: 15-external-authentication* +*Completed: 2026-04-04*