Remove docs/findings-lakehouse.md
This commit is contained in:
@@ -1,90 +0,0 @@
|
||||
# Findings — adopting `lakehouse` as a castle service
|
||||
|
||||
A completeness/UX test: take an existing daemon (`/data/repos/lakehouse`, a
|
||||
FastAPI `lakehoused` server on port 8420 that bundles its own SPA, normally
|
||||
started by a bespoke `lakehouse start`) and bring it fully under castle —
|
||||
systemd-managed, health-checked, proxied, on the dashboard.
|
||||
|
||||
## What worked cleanly
|
||||
|
||||
- `castle add` auto-detected `behavior: daemon` + `stack: python-fastapi` from
|
||||
the pyproject (fastapi/uvicorn in deps).
|
||||
- Adding the service via the config API (`PUT /config/services/lakehouse`)
|
||||
validated and persisted correctly.
|
||||
- `castle deploy lakehouse` produced a correct systemd unit, registry entry,
|
||||
and Caddy route, and auto-installed the editable package.
|
||||
- `castle service enable lakehouse` started it and enabled it on boot.
|
||||
- Health probe (direct `127.0.0.1:8420`) and dashboard data
|
||||
(program / service / deployment / `active`) were all correct.
|
||||
|
||||
## Gaps found
|
||||
|
||||
### #1 — No CLI/app path to create a service from an adopted daemon (High)
|
||||
|
||||
`castle add` writes a `daemon`-behavior **program**, but there is no command to
|
||||
turn it into a running **service** (port, health, proxy, systemd). We had to
|
||||
hand the service block to the config API. Worse: `castle install <daemon>` on a
|
||||
program with no service silently falls through to the *tool* install path
|
||||
(`uv tool install`) instead of running it — a dead end.
|
||||
|
||||
**Fix:** `castle expose <program> [--port --health --path]` to scaffold a
|
||||
service entry from an existing program. (App needs an equivalent "add service"
|
||||
flow — tracked separately.)
|
||||
|
||||
### #2 — castle can't actually configure an adopted program's port / data dir (Medium)
|
||||
|
||||
The generated unit injects castle's convention vars `LAKEHOUSE_PORT=8420` and
|
||||
`LAKEHOUSE_DATA_DIR=…`, but `lakehoused` reads **`LAKEHOUSED_DAEMON_PORT`** and
|
||||
its own storage paths — it ignores both. The port "worked" only because 8420 is
|
||||
the daemon's built-in default and we declared the same value. Castle's
|
||||
convention assumes a castle-aware program; an adopted one doesn't read
|
||||
`<PREFIX>_PORT`.
|
||||
|
||||
**Fixed** (superseding the interim `port_env` field): auto-injection of the
|
||||
convention vars was dropped entirely. A service's env is now exactly its
|
||||
`defaults.env`, with `${port}`/`${data_dir}`/`${name}` placeholders for castle's
|
||||
computed values. lakehouse maps just what it reads —
|
||||
`LAKEHOUSED_DAEMON_PORT: ${port}` — and keeps its own data root, with no dead
|
||||
vars. Castle-native services map their `<PREFIX>_PORT`/`_DATA_DIR` the same way
|
||||
(scaffolded by `castle program create`).
|
||||
|
||||
### #3 — `castle deploy` regenerates the Caddyfile but never reloads Caddy (High, bug)
|
||||
|
||||
Deploy wrote the new `/lakehouse` route to the Caddyfile on disk but didn't
|
||||
reload the running gateway, so every `/lakehouse/*` request fell through to the
|
||||
castle-app catch-all and returned the dashboard's `index.html` (a misleading
|
||||
`200`). `castle service enable` doesn't reload either, and the deploy output
|
||||
never mentions `castle gateway reload`.
|
||||
|
||||
**Fix:** `castle deploy` (and `service enable`) reload the gateway when proxy
|
||||
routes changed.
|
||||
|
||||
### #4 — Path-prefix proxying breaks root-based SPAs (Medium, architectural)
|
||||
|
||||
`lakehoused`'s bundled webapp is built with Vite `base: "/"` — its `index.html`
|
||||
references assets at absolute `/assets/…`. Proxied at `/lakehouse/`, the browser
|
||||
requests `/assets/…` (no prefix), which hits the castle-app catch-all → the UI
|
||||
can't boot. The API works through the gateway; the UI only works directly at
|
||||
`:8420/`.
|
||||
|
||||
Two distinct cases, because Vite bakes `base` in at **build** time (a runtime
|
||||
env in the unit is too late to rebase a pre-built bundle):
|
||||
|
||||
- **Case A — frontends castle builds** (the `react-vite` stack, served by
|
||||
`file_server`). Castle runs `pnpm build` *and* knows the serve prefix, so it
|
||||
can pass `--base=/<prefix>/` automatically. Today `power-graph-app` only works
|
||||
because its base was hand-set to match.
|
||||
**Fix:** derive the build `--base` from the serve path prefix.
|
||||
- **Case B — adopted daemons that self-serve a root SPA** (lakehouse). Castle
|
||||
never runs their build, so it can't pass `--base`. The clean answer is
|
||||
**host-based routing** (`lakehouse.civil.lan → :8420`) so `base: "/"` stays
|
||||
valid — also a generally useful castle capability.
|
||||
**Fix:** support proxy-by-hostname in the Caddyfile generator + manifest.
|
||||
|
||||
### Nits
|
||||
|
||||
- **Redundant editable reinstall:** `castle deploy` installs the package, then
|
||||
`castle install`/activate may `uv tool install` it again.
|
||||
- **Entry-point discovery:** the service's `run.program` had to be `lakehoused`,
|
||||
not `lakehouse` — the package ships two console scripts and castle gives no
|
||||
hint which is the server. Surfacing a package's `[project.scripts]` would help.
|
||||
Reference in New Issue
Block a user