docs(01-03): complete integration and deployment plan — SUMMARY, STATE, ROADMAP, REQUIREMENTS updated
This commit is contained in:
Claude
160
.planning/phases/01-foundation/01-03-SUMMARY.md
Normal file
160
.planning/phases/01-foundation/01-03-SUMMARY.md
Normal file
@@ -0,0 +1,160 @@
|
||||
---
|
||||
phase: 01-foundation
|
||||
plan: "03"
|
||||
subsystem: infra
|
||||
tags: [fastapi, docker, traefik, authelia, alpine, uvicorn, routing]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 01-01
|
||||
provides: FastAPI app, DeviceRegistry, ShowStore, models
|
||||
- phase: 01-02
|
||||
provides: frontend shell, static files
|
||||
|
||||
provides:
|
||||
- Working device CRUD API (POST/GET/DELETE without trailing slash)
|
||||
- Working show CRUD API (POST/GET list/GET by ID)
|
||||
- Static file serving at / via FastAPI StaticFiles
|
||||
- Device persistence across restarts via devices.json
|
||||
- Show persistence via shows/ directory
|
||||
- Dockerfile (python:3.11-alpine)
|
||||
- docker-compose.prod.yml with Traefik + Authelia labels
|
||||
- Deployed app at lightsync.groll.cloud
|
||||
- LightSync entry added to start/projects.json
|
||||
|
||||
affects: [02-audio, 03-timeline, all phases using API contracts]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [docker-compose v2.34.0 CLI plugin]
|
||||
patterns:
|
||||
- redirect_slashes=False on FastAPI app to prevent StaticFiles from intercepting API redirects
|
||||
- API route paths use "" (empty string) not "/" to avoid trailing slash requirement
|
||||
- hatchling wheel target requires explicit packages config for Docker builds
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- Dockerfile
|
||||
- docker-compose.prod.yml
|
||||
modified:
|
||||
- lightsync/main.py
|
||||
- lightsync/api/devices.py
|
||||
- lightsync/api/shows.py
|
||||
- lightsync/frontend/app.js
|
||||
- pyproject.toml
|
||||
- /home/claude/start/projects.json
|
||||
|
||||
key-decisions:
|
||||
- "redirect_slashes=False on FastAPI app — StaticFiles mount at / intercepted /api/* requests before FastAPI could redirect /api/devices -> /api/devices/"
|
||||
- "API routes use empty string paths ('') not slash ('/') — makes /api/devices the canonical path without redirect"
|
||||
- "docker-compose plugin installed manually as CLI plugin (v2.34.0) — system apt had no docker-compose-plugin"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: FastAPI + StaticFiles at root — always use redirect_slashes=False and empty-string route paths"
|
||||
- "Pattern: Docker build — add [tool.hatch.build.targets.wheel] packages config for hatchling builds outside git"
|
||||
|
||||
requirements-completed: [INF-01, DEV-01, DEV-02, DEV-03, SHW-01, SHW-02, UI-01]
|
||||
|
||||
# Metrics
|
||||
duration: 6min
|
||||
completed: "2026-04-05"
|
||||
---
|
||||
|
||||
# Phase 01 Plan 03: Integration and Deployment Summary
|
||||
|
||||
**FastAPI device+show CRUD working end-to-end, deployed to lightsync.groll.cloud on python:3.11-alpine behind Authelia**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 6 min
|
||||
- **Started:** 2026-04-05T18:53:06Z
|
||||
- **Completed:** 2026-04-05T18:59:48Z
|
||||
- **Tasks:** 1
|
||||
- **Files modified:** 7 (+ 2 created)
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Diagnosed and fixed StaticFiles/routing conflict — /api/devices (no trailing slash) was intercepted by StaticFiles before FastAPI redirect
|
||||
- All API endpoints verified: POST/GET/DELETE devices, POST/GET list/GET by ID for shows, GET / returns LIGHTSYNC HTML
|
||||
- Device persistence verified across server restart (devices.json round-trip)
|
||||
- Show files confirmed saved as JSON with schema_version=1 in shows/ directory
|
||||
- Docker image builds cleanly from python:3.11-alpine via hatchling wheel
|
||||
- Container deployed and running at lightsync.groll.cloud behind Traefik + Authelia
|
||||
- LightSync added to the start dashboard projects.json
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Integration test, routing fix, Docker deployment** - `a21962c` (feat)
|
||||
|
||||
**Plan metadata:** _(docs commit follows)_
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `Dockerfile` - python:3.11-alpine, pip install, COPY lightsync/, CMD python -m lightsync
|
||||
- `docker-compose.prod.yml` - Traefik labels for lightsync.groll.cloud + authelia@docker middleware, edge network
|
||||
- `lightsync/main.py` - Added redirect_slashes=False to FastAPI app
|
||||
- `lightsync/api/devices.py` - Routes changed from "/" to "" (empty string)
|
||||
- `lightsync/api/shows.py` - Routes changed from "/" to "" (empty string)
|
||||
- `lightsync/frontend/app.js` - Changed /api/devices/ to /api/devices (no trailing slash)
|
||||
- `pyproject.toml` - Added [tool.hatch.build.targets.wheel] packages = ["lightsync"]
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **redirect_slashes=False**: FastAPI's default redirect behavior (307 from /api/devices → /api/devices/) was being intercepted by the StaticFiles mount at root. Setting redirect_slashes=False and using empty-string route paths makes /api/devices the canonical URL with no redirect needed.
|
||||
- **Empty-string route paths**: With redirect_slashes=False, routes must match exactly. Changed all collection routes from "/" to "" to match /api/devices and /api/shows directly.
|
||||
- **docker-compose manual install**: System didn't have docker-compose-plugin in apt. Downloaded v2.34.0 binary from GitHub and installed as ~/.docker/cli-plugins/docker-compose.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Fixed StaticFiles intercepting API routes without trailing slash**
|
||||
- **Found during:** Task 1 (smoke testing device CRUD)
|
||||
- **Issue:** POST /api/devices returned 405, GET /api/devices returned 404. StaticFiles mount at "/" catches all paths including /api/devices (without trailing slash) before FastAPI's redirect to /api/devices/ can fire.
|
||||
- **Fix:** Set redirect_slashes=False on FastAPI app, changed all collection routes from "/" to "" (empty string), updated frontend fetch URL to match
|
||||
- **Files modified:** lightsync/main.py, lightsync/api/devices.py, lightsync/api/shows.py, lightsync/frontend/app.js
|
||||
- **Verification:** POST /api/devices returns 201, GET /api/devices returns 200, all CRUD operations verified
|
||||
- **Committed in:** a21962c
|
||||
|
||||
**2. [Rule 1 - Bug] Fixed hatchling build failure in Docker**
|
||||
- **Found during:** Task 1 (Docker build step)
|
||||
- **Issue:** `pip install .` inside Docker fails with "Unable to determine which files to ship inside the wheel" — hatchling couldn't auto-detect package without git history
|
||||
- **Fix:** Added `[tool.hatch.build.targets.wheel] packages = ["lightsync"]` to pyproject.toml
|
||||
- **Files modified:** pyproject.toml
|
||||
- **Verification:** Docker build succeeds, image tagged and running
|
||||
- **Committed in:** a21962c
|
||||
|
||||
**3. [Rule 3 - Blocking] Installed missing docker-compose plugin**
|
||||
- **Found during:** Task 1 (deploy step)
|
||||
- **Issue:** deploy.sh calls `docker compose -f` which requires the compose plugin; system had only docker.io 28.2.2 without compose plugin
|
||||
- **Fix:** Downloaded docker-compose v2.34.0 binary from GitHub releases, installed to ~/.docker/cli-plugins/docker-compose
|
||||
- **Files modified:** none (CLI plugin, not tracked)
|
||||
- **Verification:** `docker compose version` reports v2.34.0, deploy.sh runs successfully
|
||||
- **Committed in:** a21962c (infrastructure fix, no tracked file changes)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 3 auto-fixed (2 Rule 1 bugs, 1 Rule 3 blocking)
|
||||
**Impact on plan:** All three fixes necessary for the plan's core goal (working API + Docker deployment). No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- httpx `AsyncClient(app=app)` syntax deprecated — newer httpx requires `ASGITransport`. Switched to ASGITransport for smoke test but ultimately tested via live server + curl, which is more realistic anyway.
|
||||
- Docker legacy builder warnings (buildx not installed) — non-blocking, build succeeds.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Full foundation is complete: device CRUD, show CRUD, StaticFiles serving, Docker deployment
|
||||
- All Phase 1 success criteria met: device persistence, show JSON files, frontend loads, app in Docker at lightsync.groll.cloud
|
||||
- Phase 2 can start building audio loading and timeline editor on this foundation
|
||||
- API contracts are stable: /api/devices and /api/shows both work without trailing slashes
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
All files verified present. Task commit a21962c confirmed in git log. Container running (lightsync Up ~2 minutes). SUMMARY.md created. STATE.md updated. ROADMAP.md updated (Phase 1: 3/3 plans, Complete). Requirements DEV-03 and UI-01 marked complete.
|
||||
|
||||
---
|
||||
*Phase: 01-foundation*
|
||||
*Completed: 2026-04-05*
|
||||
Reference in New Issue
Block a user