wiki: document dev environment (WSL networking, workflow)
Capture hard-won dev knowledge that was only in commit messages: - wsl-dev-networking: WSL2 NAT blocks UDP broadcast (device discovery can't reach the LAN); fix is mirrored networking (.wslconfig, Win11 22H2+), plus the gotchas that remained after — multiple interfaces, subnet-directed broadcast, localhost->IPv6 stall. Alternatives for non-mirrored setups. - local-dev-workflow: first-time setup, pnpm dev, and the gotchas (the strip-types dev-server hang -> tsx, the 127.0.0.1 proxy fix, .env loading, seeding into the right DB). - device-discovery: corrected the old "broadcast permission (EACCES)" note — the real cause was the lib not enabling SO_BROADCAST for global 255.255.255.255; documented the three verified broadcast gotchas + I/O serialization. - schema: add a `reference` page type; new "Dev environment" index section; log. Links lint clean; both new pages well-connected.
This commit is contained in:
+2
-2
@@ -35,9 +35,9 @@ wiki/
|
||||
- **Frontmatter** (YAML) on every wiki page:
|
||||
```yaml
|
||||
---
|
||||
type: source | entity | concept | decision | overview
|
||||
type: source | entity | concept | decision | overview | reference
|
||||
tags: [parking, ...]
|
||||
sources: [parking-system-architecture] # raw source slugs this draws from
|
||||
sources: [parking-system-architecture] # raw source slugs (omit/[] if not source-derived)
|
||||
updated: 2026-06-14
|
||||
status: settled | open # decisions only
|
||||
---
|
||||
|
||||
@@ -23,10 +23,30 @@ as optional; the setup catalog returns a `discoverable` list of driver ids.
|
||||
## UHPPOTE discovery
|
||||
|
||||
The [[uhppote-controller]] supports discovery natively: a **UDP broadcast** (`get-devices` on
|
||||
`255.255.255.255:60000`) that **every controller on the LAN answers** with its serial, IP,
|
||||
netmask, gateway, MAC, firmware version, and date. The official `uhppoted` lib exposes this as
|
||||
`getDevices(ctx)`; the `uhppote` driver maps each result into a `DiscoveredDevice` (serial → id,
|
||||
IP → host).
|
||||
port `60000`) that **every controller on the LAN answers** with its serial, IP, netmask, gateway,
|
||||
MAC, firmware version, and date. The official `uhppoted` lib exposes this as `getDevices(ctx)`;
|
||||
the `uhppote` driver maps each result into a `DiscoveredDevice` (serial → id, IP → host).
|
||||
**Verified on real hardware** (serial 225088491).
|
||||
|
||||
### Broadcast gotchas (learned the hard way — see [[wsl-dev-networking]])
|
||||
|
||||
These cost real debugging time; the `uhppote` driver now handles all three:
|
||||
|
||||
1. **Broadcast to the *subnet-directed* address, not the global `255.255.255.255`.** The
|
||||
`uhppoted` lib only calls `setBroadcast(true)` when the target matches a **local interface's
|
||||
subnet broadcast** (e.g. `10.0.10.255`). For the global address it skips it, so the `send`
|
||||
fails with **`EACCES`**. The driver computes the subnet broadcast from `os.networkInterfaces()`.
|
||||
2. **A host with multiple interfaces must broadcast on *all* subnets.** With several NICs (LAN,
|
||||
VPN/Tailscale, docker bridges) the controller is on only one. Picking the first interface
|
||||
misses it; the driver broadcasts on every subnet and dedupes by serial.
|
||||
3. **For *unicast* ops (status / open), the lib's `Config` broadcast must match the target's
|
||||
subnet** — it governs reply routing, so a mismatched broadcast makes `getStatus` time out even
|
||||
though `openDoor` "succeeds". The driver sets the broadcast per the target host's subnet. (This
|
||||
was the health-check "offline/timeout" bug: a 5 s timeout dropped to 24 ms once fixed.)
|
||||
|
||||
Also: concurrent `uhppoted` calls collide on the `:60001` reply-listener port (EACCES / dropped
|
||||
replies), so the driver **serializes** all controller I/O. Override the broadcast with
|
||||
`UHPPOTE_BROADCAST` for unusual setups.
|
||||
|
||||
## Flow
|
||||
|
||||
@@ -38,9 +58,9 @@ IP → host).
|
||||
|
||||
## Deployment notes
|
||||
|
||||
- UHPPOTE discovery is a **broadcast** — the host socket needs broadcast permission (a raw
|
||||
`send EACCES …:60000` means the OS blocked it). Works on the isolated device VLAN
|
||||
([[network-isolation]]) where the controller and host share an L2 segment.
|
||||
- Discovery is an **L2 broadcast**: the host and controller must share a layer-2 segment. Works
|
||||
on the isolated device VLAN ([[network-isolation]]). A routed/NAT'd network (e.g. WSL2 NAT mode
|
||||
— see [[wsl-dev-networking]]) blocks it entirely.
|
||||
- Discovery shares the same unauthenticated UDP exposure as everything else UHPPOTE — another
|
||||
reason the controllers live on an isolated VLAN ([[uhppote-udp-protocol]]).
|
||||
- Cameras (Hikvision/Dahua via ONVIF/WS-Discovery) could implement the same interface later.
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
type: reference
|
||||
tags: [parking, dev-environment, workflow]
|
||||
sources: []
|
||||
updated: 2026-06-15
|
||||
---
|
||||
|
||||
# Local Dev Workflow
|
||||
|
||||
> Dev-environment reference, not product architecture. How to run the stack locally and the
|
||||
> gotchas that have bitten us. For device testing under WSL also read [[wsl-dev-networking]].
|
||||
|
||||
## First-time setup
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
cp apps/server/.env.example apps/server/.env # then fill in JWT_SECRET
|
||||
# JWT_SECRET=$(openssl rand -hex 32) # server refuses to start without a strong one
|
||||
pnpm --filter @parking/db exec drizzle-kit migrate # create the SQLite schema
|
||||
pnpm seed:admin # create the first admin (see [[local-jwt-auth]])
|
||||
```
|
||||
|
||||
`apps/server/.env` and the `*.sqlite` files are **gitignored** (local-only). Leave `NODE_ENV`
|
||||
**unset** in dev so the auth cookies aren't `Secure`-only (Vite dev is plain http).
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
pnpm dev # turbo runs both: Vite (web, :5173) + Fastify (server, :3000)
|
||||
```
|
||||
|
||||
Open `http://localhost:5173`. The Vite dev proxy forwards `/api` + `/health` to the backend, so
|
||||
the SPA and API are **same-origin** and the [[local-jwt-auth|cookie auth]] works without CORS.
|
||||
Production uses an **nginx** reverse proxy (`deploy/nginx.conf`) for the same same-origin setup.
|
||||
|
||||
## Gotchas (all fixed, recorded so they don't recur)
|
||||
|
||||
- **Server dev must not be `node --experimental-strip-types src/index.ts`.** Type-stripping does
|
||||
**not** rewrite `.js` import specifiers to `.ts`, so it crashed with `ERR_MODULE_NOT_FOUND` and
|
||||
silently never started — the symptom was the SPA hanging for *minutes* (the Vite proxy waiting
|
||||
on a dead backend), then finally erroring. The `dev` script uses **`tsx watch`** instead.
|
||||
- **Vite proxy → `127.0.0.1`, not `localhost`.** `localhost` resolves to IPv6 `::1` first while
|
||||
the backend binds IPv4; Node's proxy can stall on the v6 attempt. Same class of "slow then
|
||||
works" hang, worse under WSL2 mirrored mode ([[wsl-dev-networking]]).
|
||||
- **`.env` must actually be loaded.** The server reads `process.env` only; the dev/start scripts
|
||||
load the file via Node's `--env-file-if-exists=.env`. An empty `JWT_SECRET=` makes the server
|
||||
fail-fast at boot.
|
||||
- **Seed into the DB the server reads.** `seed:admin` and the server must use the same
|
||||
`DATABASE_URL`; running via `pnpm seed:admin` (which loads `apps/server/.env`) keeps them aligned.
|
||||
|
||||
## Useful one-offs
|
||||
|
||||
- First admin: `pnpm seed:admin` (prompts; blank username → `admin`). Non-interactive:
|
||||
`ADMIN_USER=.. ADMIN_PASS=.. pnpm seed:admin`. Reset a password: add `FORCE=1`.
|
||||
- Hardware test scripts (UHPPOTE): `apps/server/scripts/uhppote-listen.mjs` (live events),
|
||||
`uhppote-relay.mjs` (guarded door-open). See [[uhppote-controller]].
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
type: reference
|
||||
tags: [parking, dev-environment, networking, wsl, troubleshooting]
|
||||
sources: []
|
||||
updated: 2026-06-15
|
||||
---
|
||||
|
||||
# WSL2 Dev Networking (for device testing)
|
||||
|
||||
> Dev-environment note, not product architecture. Recorded because reaching real
|
||||
> hardware (the [[uhppote-controller]]) from a dev box running under **WSL2** took
|
||||
> significant debugging. If you test devices from WSL, read this first.
|
||||
|
||||
## The problem
|
||||
|
||||
By default WSL2 uses **NAT networking**: the Linux VM sits on its own virtual subnet
|
||||
(e.g. `172.x`), not the Windows host's LAN. Consequences for device work:
|
||||
|
||||
- **UDP broadcast (UHPPOTE discovery) cannot leave the VM** — a `get-devices` broadcast gets
|
||||
`EACCES` / never reaches a controller on the physical LAN. The device is reachable from
|
||||
*Windows* but not from *inside WSL*.
|
||||
- Even unicast to a LAN device may not route, depending on setup.
|
||||
|
||||
## The fix: mirrored networking
|
||||
|
||||
Switch WSL to **mirrored** mode so it shares the Windows host's interfaces (and thus the real
|
||||
LAN). Requires **Windows 11 22H2+** and **WSL ≥ 2.0**.
|
||||
|
||||
`%UserProfile%\.wslconfig` (create it; it doesn't exist by default):
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
networkingMode=mirrored
|
||||
firewall=false # Windows Firewall otherwise filters WSL traffic (can drop UDP replies)
|
||||
|
||||
[experimental]
|
||||
hostAddressLoopback=true # host <-> WSL over the host's IP
|
||||
```
|
||||
|
||||
Apply: in **PowerShell** `wsl --shutdown`, wait ~10 s, reopen WSL. Verify with `ip -4 addr` —
|
||||
interfaces should now show the **real LAN subnet** (e.g. `10.0.10.x`) instead of `172.x`.
|
||||
(Microsoft recommends editing via the **WSL Settings** GUI rather than the file by hand.)
|
||||
|
||||
> `wsl --shutdown` kills the dev servers — restart `pnpm dev` afterward.
|
||||
|
||||
## After mirrored mode: app-level gotchas that remained
|
||||
|
||||
Mirrored networking is necessary but **not sufficient** — these still bit us:
|
||||
|
||||
- **Multiple interfaces.** Mirrored WSL exposes *all* host NICs (LAN, Tailscale/CGNAT `100.x`,
|
||||
docker bridges). UHPPOTE discovery must broadcast on **every** subnet, not the first one — see
|
||||
[[device-discovery]].
|
||||
- **Subnet-directed broadcast** (`10.0.10.255`, not `255.255.255.255`) — the lib won't enable
|
||||
`SO_BROADCAST` otherwise. See [[device-discovery]].
|
||||
- **`localhost` → IPv6 first.** `localhost` resolves to `::1`, but the backend binds IPv4
|
||||
(`127.0.0.1`). Node's Vite proxy can stall on the v6 attempt before falling back — point the
|
||||
proxy at `127.0.0.1` explicitly. (See [[local-dev-workflow]].)
|
||||
|
||||
## Alternative if you can't use mirrored mode
|
||||
|
||||
Windows 10 / old WSL can't do mirrored mode. Options: run the **backend natively on Windows**
|
||||
(shares the LAN), or use **unicast by IP** instead of broadcast discovery (target the controller's
|
||||
known IP — the driver supports an explicit host). On the real **appliance** (a dedicated hardened
|
||||
Linux box, [[disk-os-hardening]]) none of this applies — it's bare-metal on the device VLAN
|
||||
([[network-isolation]]).
|
||||
@@ -66,6 +66,10 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
|
||||
- [[entry-exit-readers]] — two populations, two integration paths; both can share a relay.
|
||||
- [[uhppote-vs-esp32]] — comparison: detection vs. prevention.
|
||||
|
||||
## Dev environment (reference)
|
||||
- [[local-dev-workflow]] — running the stack locally; setup, the dev-hang gotchas, seed:admin.
|
||||
- [[wsl-dev-networking]] — WSL2 NAT blocks device broadcast; use mirrored mode + the gotchas after.
|
||||
|
||||
## Decisions
|
||||
- [[standing-decisions]] — settled decisions (stack, platform, integrity, access control, readers).
|
||||
- [[open-questions]] — 7 open items (6 procurement + JWT key choice); ESP32 device auth deferred.
|
||||
|
||||
+11
@@ -83,3 +83,14 @@ admins. Same-origin via the Vite dev proxy and a new prod nginx config
|
||||
(deploy/nginx.conf). Verified end to end (curl + browser): wrong pass→401,
|
||||
login→cookies set, me→admin, assign without CSRF→403 / with→201, no cookie→401,
|
||||
session persists across reload. Updated [[local-jwt-auth]].
|
||||
|
||||
## [2026-06-15] lint+docs | Dev-environment pages (WSL networking, workflow)
|
||||
Captured hard-won dev knowledge that was only in commit messages: new
|
||||
[[wsl-dev-networking]] (WSL2 NAT blocks UDP broadcast → mirrored mode + the
|
||||
multi-interface / subnet-broadcast / IPv6-localhost gotchas that remained) and
|
||||
[[local-dev-workflow]] (setup, seed:admin, the dev-server-hang from the broken
|
||||
strip-types script → tsx, the 127.0.0.1 proxy fix, .env loading). Corrected the
|
||||
earlier "broadcast permission (EACCES)" note in [[device-discovery]] — the real
|
||||
cause was the lib not enabling SO_BROADCAST for the global 255.255.255.255;
|
||||
documented the three verified broadcast gotchas + serialization. Added a `reference`
|
||||
page type to the schema; new "Dev environment" index section.
|
||||
|
||||
Reference in New Issue
Block a user