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