133 lines
8.9 KiB
Markdown
133 lines
8.9 KiB
Markdown
---
|
|
phase: 01-project-infrastructure-module-wiring
|
|
plan: 05
|
|
subsystem: infra
|
|
tags: [ktor, flyway, hocon, postgres, slf4j, kotlinx-serialization]
|
|
|
|
requires:
|
|
- phase: 01-project-infrastructure-module-wiring
|
|
provides: "recipe.jvm.server precompiled plugin (Plan 02) wires ktor-server-netty, ktor-server-content-negotiation, ktor-serialization-kotlinx-json, flyway-core, flyway-database-postgresql, postgresql JDBC, ktor-server-test-host, logback-classic. Plan 03 applied recipe.jvm.server + recipe.quality to server module and added implementation(projects.shared) so SERVER_PORT is reachable."
|
|
provides:
|
|
- "Running-but-empty server: GET /health returns {\"status\":\"ok\"} with Content-Type application/json"
|
|
- "HOCON application.conf with localhost defaults + ${?ENV} overrides for PORT/DATABASE_URL/DATABASE_USER/DATABASE_PASSWORD"
|
|
- "Database.migrate() Flyway boot sequence with fail-loud IllegalStateException contract on unreachable Postgres"
|
|
- "server/src/main/resources/db/migration/ resource directory anchored by .gitkeep so classpath:db/migration resolves before Phase 3 adds V1__init.sql"
|
|
- "configureRouting() extension extracted from Application.module() so tests compose routing without invoking Database.migrate (no Postgres in CI)"
|
|
affects: [phase-02-auth, phase-03-households, phase-05-recipe-catalog, phase-11-deployment]
|
|
|
|
tech-stack:
|
|
added: [Flyway runtime API (flyway-core 12.x), HOCON env-var override pattern, SLF4J server-side logging]
|
|
patterns:
|
|
- "HOCON ${?ENV} two-line override pattern (PITFALL #5 mitigation)"
|
|
- "Fail-loud server boot: Database.migrate throws IllegalStateException on Flyway/JDBC failure"
|
|
- "Routing extracted to Application.configureRouting() extension so testApplication composes routing without DB dependency"
|
|
- "Server uses SLF4J/Logback (NOT Kermit — Kermit is client-only)"
|
|
|
|
key-files:
|
|
created:
|
|
- server/src/main/kotlin/dev/ulfrx/recipe/Database.kt
|
|
- server/src/main/resources/application.conf
|
|
- server/src/main/resources/db/migration/.gitkeep
|
|
modified:
|
|
- server/src/main/kotlin/dev/ulfrx/recipe/Application.kt
|
|
- server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt
|
|
|
|
key-decisions:
|
|
- "Use HOCON ${?ENV} optional substitution (two-line default + override) rather than ${ENV:default} (invalid HOCON) or ${ENV} (required, crashes on unset)"
|
|
- "Server logs via SLF4J/Logback, not Kermit — Kermit reserved for the multiplatform client"
|
|
- "Database.migrate is fail-loud: IllegalStateException on any Flyway error; no silent degraded mode"
|
|
- "cleanDisabled(true) is double-enforced (precompiled plugin CLI guard + programmatic Database.migrate guard)"
|
|
- "Extract Application.configureRouting() so /health test runs without Postgres — preserves D-11 invariant that ./gradlew :server:test passes in fresh clones / CI"
|
|
- "Default credentials in application.conf (recipe/recipe/recipe @ localhost:5432/recipe) match Plan 06 docker-compose for zero-config dev boot"
|
|
|
|
patterns-established:
|
|
- "HOCON ${?ENV} override: every secret/per-env value gets a default line followed by ${?ENV_VAR} optional substitution"
|
|
- "Fail-loud infrastructure: critical boot operations (DB migration, future JWKS load) throw IllegalStateException rather than returning a status"
|
|
- "Routing extraction for testability: features expose Application.configureXxx() extensions; module() is the production composition root"
|
|
|
|
requirements-completed: [INFRA-02]
|
|
|
|
duration: ~1 min (executor work — implementation commits authored ahead of executor invocation)
|
|
completed: 2026-04-24
|
|
---
|
|
|
|
# Phase 01 Plan 05: Server /health + Flyway + HOCON Boot Summary
|
|
|
|
**Running-but-empty Ktor server: HOCON-configured Flyway boot with fail-loud Postgres contract, GET /health returning `{"status":"ok"}`, and a routing extraction that lets tests verify the route without a running database.**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** Implementation commits span 2026-04-24 18:22:08 → 18:23:14 (~66s of authoring); executor verification + SUMMARY ~1 min
|
|
- **Started:** 2026-04-24T18:22:08Z (commit 24018ef)
|
|
- **Completed:** 2026-04-24T18:23:14Z (commit 59d0695)
|
|
- **Tasks:** 3
|
|
- **Files modified:** 5 (3 created, 2 modified)
|
|
|
|
## Accomplishments
|
|
|
|
- HOCON `application.conf` reads PORT + DATABASE_URL/USER/PASSWORD via the `${?ENV}` two-line override pattern; defaults match the Plan 06 docker-compose stack so `docker compose up -d postgres && ./gradlew :server:run` works with zero env config.
|
|
- `Database.migrate(app: Application)` runs `Flyway.configure().dataSource(...).locations("classpath:db/migration").baselineOnMigrate(true).validateOnMigrate(true).cleanDisabled(true).load().migrate()` and throws `IllegalStateException` on any failure — D-16 fail-loud contract satisfied.
|
|
- `db/migration/.gitkeep` keeps the resource directory in the repo so Flyway's classpath resolution succeeds before Phase 3 introduces the first SQL migration.
|
|
- `Application.kt` rewritten with explicit Ktor imports (D-11 allWarningsAsErrors clean), installs `ContentNegotiation { json() }`, calls `Database.migrate(this)`, then delegates to `Application.configureRouting()` which exposes `GET /health → Health(status="ok")`.
|
|
- `ApplicationTest.kt` rewritten to compose `configureRouting()` directly (skipping `Database.migrate`) so `./gradlew :server:test --tests "*health*"` passes without a running Postgres — required for fresh-clone / CI runs.
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically prior to executor invocation (commits already in branch history):
|
|
|
|
1. **Task 1: HOCON config + db/migration/.gitkeep + Database.kt** — `24018ef` (feat)
|
|
2. **Task 2: Application.kt rewrite (ContentNegotiation, Flyway boot, /health)** — `daefe6c` (refactor)
|
|
3. **Task 3: ApplicationTest.kt rewrite (no-Postgres /health assertion)** — `59d0695` (test)
|
|
|
|
**Plan metadata:** appended in this commit (docs).
|
|
|
|
## Files Created/Modified
|
|
|
|
- `server/src/main/resources/application.conf` (created) — HOCON config: ktor.deployment.port + database.{url,user,password} with `${?ENV}` overrides
|
|
- `server/src/main/resources/db/migration/.gitkeep` (created) — anchors the Flyway classpath resource directory in git
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` (created) — `object Database { fun migrate(app) }` with fail-loud Flyway invocation, SLF4J logging
|
|
- `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` (modified) — explicit imports; installs ContentNegotiation; runs Database.migrate; delegates to configureRouting(); exposes GET /health returning serializable `Health(status)`
|
|
- `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` (modified) — replaces template `testRoot()` with health-endpoint test that composes routing without DB
|
|
|
|
## Decisions Made
|
|
|
|
See `key-decisions` in frontmatter. Highlights:
|
|
|
|
- HOCON `${?ENV}` optional substitution chosen over `${ENV}` (required) and `${ENV:default}` (invalid HOCON) per PITFALL #5.
|
|
- Server logging via SLF4J/Logback (not Kermit) because Logback is already wired in `recipe.jvm.server` and Kermit is reserved for the multiplatform client.
|
|
- `Application.configureRouting()` extension extracted to satisfy the no-Postgres-required invariant for `./gradlew :server:test`.
|
|
|
|
## Deviations from Plan
|
|
|
|
None — plan executed exactly as written. All artifacts match the plan's `must_haves` (truths, artifacts, key_links) verified against the filesystem; explicit imports satisfy D-11; `${?ENV}` lines all present; fail-loud contract intact; `Database.migrate` not referenced from the test.
|
|
|
|
## Issues Encountered
|
|
|
|
None.
|
|
|
|
## User Setup Required
|
|
|
|
None — no external service configuration required. Postgres for end-to-end boot is provided by the Plan 06 docker-compose stack; Plan 05's own success criteria (test passing without a running DB) require nothing from the operator.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Phase 2 (Auth) inherits a Ktor server with ContentNegotiation pre-installed, so JWT validation routes can return `@Serializable` DTOs immediately.
|
|
- Phase 3 (Households) drops `V1__init.sql` into `server/src/main/resources/db/migration/`; the Flyway boot pathway is already validated.
|
|
- Phase 11 (Deployment) inherits the HOCON `${?ENV}` pattern; homelab deploy configures `DATABASE_URL/USER/PASSWORD` via env vars without touching `application.conf`.
|
|
- Manual end-to-end verification (`docker compose up -d postgres && ./gradlew :server:run && curl http://localhost:8080/health`) deferred to Plan 07 / manual smoke per the plan's verification section.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- File `server/src/main/resources/application.conf` — FOUND
|
|
- File `server/src/main/resources/db/migration/.gitkeep` — FOUND
|
|
- File `server/src/main/kotlin/dev/ulfrx/recipe/Database.kt` — FOUND
|
|
- File `server/src/main/kotlin/dev/ulfrx/recipe/Application.kt` — FOUND
|
|
- File `server/src/test/kotlin/dev/ulfrx/recipe/ApplicationTest.kt` — FOUND
|
|
- Commit `24018ef` (feat 01-05 Task 1) — FOUND in git log
|
|
- Commit `daefe6c` (refactor 01-05 Task 2) — FOUND in git log
|
|
- Commit `59d0695` (test 01-05 Task 3) — FOUND in git log
|
|
|
|
---
|
|
*Phase: 01-project-infrastructure-module-wiring*
|
|
*Completed: 2026-04-24*
|