diff --git a/headscale/README.md b/headscale/README.md index 1c39579..c8aff8c 100644 --- a/headscale/README.md +++ b/headscale/README.md @@ -134,6 +134,123 @@ docker exec -it headscale kill -HUP 1 Then inspect the container logs for policy parse results. +## Owner-facing Headplane pilot checklist + +This section is for John as the stack owner using the Web UI. Doris should handle the CLI and backend admin work; this checklist is about what John should look for in Headplane and when to escalate. + +### Where to go + +- Open: `http://headplane.home.paccoco.com:3005/admin` +- Log in with the temporary Headscale API key Doris generated for the pilot + +### What you should expect to see first + +After initial pilot bring-up, Headplane should show: +- two users: + - `fizzlepoof` + - `manndra` +- John's enrolled device(s) +- one tagged pilot service node +- a generally healthy/online control plane with no obvious UI errors + +If any of those are missing, that is a Doris problem to fix, not a John problem to debug. + +### UI-first smoke test + +#### 1. Confirm the users exist +Look for: +- `fizzlepoof` +- `manndra` + +Good: +- both users appear once + +Bad / message Doris if: +- a user is missing +- a duplicate or unexpected user exists +- user ownership looks wrong + +#### 2. Confirm John's device is present +Look for at least one clearly identifiable John-owned device. + +Good: +- device shows as online +- device is owned by `fizzlepoof` +- the name is recognizable enough to tell what it is + +Bad / message Doris if: +- device is offline when it should be online +- device is attached to the wrong user +- device appears more than once unexpectedly + +#### 3. Confirm Manndra's device is present +Good: +- device is owned by `manndra` +- it appears separately from John's devices + +Bad / message Doris if: +- it shows under the wrong user +- it never appears after enrollment +- it appears to have broad access it should not have + +#### 4. Confirm the tagged node looks like a service node +Look for one node tagged as a pilot service node, typically with `tag:apps` or `tag:infra`. + +Good: +- the node is visibly tagged +- it is not owned like a normal human personal device +- it is online when the underlying service is online + +Bad / message Doris if: +- the node is untagged +- it appears owned like a personal device when it should be infra +- it has the wrong tag + +#### 5. Confirm the UI is usable enough to keep +Good: +- pages load consistently +- node/user details are understandable +- no obvious blank/error screens +- refreshing does not randomly lose state + +Bad / message Doris if: +- login repeatedly fails with a known-good API key +- pages partially load or spin forever +- the UI looks disconnected from reality +- the UI feels too broken to trust for visibility + +### Expected access behavior + +John does not need to test raw ACL syntax. The practical expectations are: + +- `fizzlepoof` should have broad pilot visibility/access +- `manndra` should be limited to app-level access +- Manndra should **not** have broad admin/infra access by default + +If Manndra can reach something that feels like core infra/admin, treat that as a problem and tell Doris. + +### What counts as pilot success from John's side + +The pilot is good enough to continue if: +- Headplane reliably loads +- the users/nodes make sense at a glance +- John's devices are visible +- Manndra's device is visible and separated correctly +- the tagged service node is visible and clearly infra-like +- nothing suggests accidental overexposure + +### When John should call Doris instead of poking at it + +Call Doris if: +- login stops working +- users disappear or duplicate +- devices are attached to the wrong owner +- a tagged node loses its tag or looks wrong +- Manndra appears to have too much access +- the UI starts showing stale, contradictory, or obviously broken state + +The point of the Web UI is visibility and confidence, not pushing John into VPN-control-plane babysitting. + ## What to validate before expanding - Headscale stays healthy