Setup & running
How to get horrible-dashboard running from a fresh clone — the browser layout and the desktop (Electron) layout share one frontend, so most of the setup is common.
package.jsonThe Scripts reference below mirrors the scripts block in the
repo-root package.json. If you add, rename, or change a pnpm script, update this
page in the same change (a Stop hook flags a package.json change that doesn't touch
docs/). See the sync policy.
Prerequisites
| Tool | Version | Notes |
|---|---|---|
| Node.js | LTS (≥ 20) | Runtime for pnpm and Vite. |
| pnpm | 10.28.2 | Pinned via packageManager. Easiest: corepack enable (uses the pinned version automatically). |
| Python | ≥ 3.12 | The backend (requires-python = ">=3.12"). |
| uv | latest | Python package/venv manager — install guide. The backend is managed with uv, never pip. |
| Electron | from pnpm install | Desktop layout only. Nothing to install by hand: Electron is a devDependency of apps/desktop, and its runtime downloads on first use. No Rust toolchain or system webview is needed. On Linux a sandboxed Electron needs unprivileged user namespaces (or run it with --no-sandbox). |
Install
corepack enable # make the pinned pnpm available (first time only)
pnpm install # JS deps for every workspace (apps/*, packages/*)
uv sync # backend Python deps + a local .venv
Optional: uv sync --extra webrtc adds the WebRTC data-channel transport for the peer
fabric (heavy native deps, so it's opt-in).
Run the browser layout
pnpm dev # backend + Vite UI + game server together
Open http://localhost:5173. pnpm dev (via scripts/dev.mjs) starts the FastAPI
backend on :8000, the Vite UI on :5173 (which proxies /api and /ws to the
backend, so API panels work out of the box), and the central game
server on :9200 so the games module works with no extra steps.
Backend health check: GET http://localhost:8000/api/health.
- Local environment variables (
.env).pnpm devautomatically loads a.envfile at the repository root if one is present, allowing you to configure local environment variables (such asGAMES_GOOGLE_CLIENT_IDor custom port overrides) for the development processes. pnpm dev:web— UI only, when a backend is already running.pnpm dev:lan— bind both servers to0.0.0.0so other machines can reach this node (needed for the peer fabric / collaboration).pnpm dev --no-gameserver(orHORRIBLE_DEV_NO_GAMESERVER=1) — skip the bundled game server, e.g. when you run one yourself or point at a hosted one. The game server is a standalone/central service (hosted in production, not per-node), so bundling it intopnpm devis purely a local-dev convenience; if:9200is already in use it just logs a warning and the rest of the stack stays up.
Run the desktop layout (Electron)
pnpm dev:desktop # LAN-reachable by default
pnpm dev:desktop --host 127.0.0.1 # local only
This starts the Vite dev server and the Electron shell (apps/desktop) together; the
shell loads the dev server (hot reload works as in the browser) and supervises the
backend itself (apps/desktop/src/backend.ts): it spawns uvicorn, or reuses one
already running on :8000 — no separate backend start needed. Closing the window stops
the backend and Vite, and so do Ctrl+C and closing the terminal. F12 or Ctrl+Shift+I
opens DevTools in development.
If :5173 is already taken, the launcher stops before starting anything and names the process holding it (on Linux and macOS) — nearly always a dev server left over from an earlier session.
Unlike pnpm dev, the desktop layout defaults to 0.0.0.0 — the equivalent of
dev:lan for the browser layout. The desktop node is the one you pair a phone with and
run the peer fabric from, so the
Android companion, remote control, and cross-node
hassault matches all need the backend off the loopback. scripts/dev-desktop.mjs sets
HORRIBLE_DEV_HOST, which is the single host knob the rest of the stack already reads
(apps/web/vite.config.ts for the Vite dev server, bindHost() in
apps/desktop/src/backend.ts for uvicorn); pass --host 127.0.0.1 or set the variable yourself to opt back out.
That exposes an unauthenticated API to the network, exactly as pnpm dev:lan does —
fine on a home or office LAN, not on untrusted wifi. The default only applies to this dev
launcher: the shell still falls back to loopback for any other caller, so a packaged
build stays local-only.
The supervisor reuses a backend already listening on :8000 rather than spawning a
duplicate, and it cannot change how that one was bound. It only reuses one it can
identify: the listener has to answer GET /api/health as horrible-dashboard. If
something else holds the port (a Docker container, another dev server), the terminal
prints [desktop] port 8000 is held by something that is not this app's backend and the
shell starts its own backend on a free port instead. Set HORRIBLE_DEV_BACKEND_PORT to
pick a different port. So pnpm dev (loopback) in one
terminal plus pnpm dev:desktop in another leaves the node unreachable from the LAN
despite the desktop default. Use pnpm dev:lan for the browser stack, or stop it and let
the desktop shell own the backend.
Production builds
pnpm build # static web bundle (apps/web/dist)
pnpm build:desktop # the web bundle, then this platform's desktop installers
build:desktop writes installers to apps/desktop/release/ (NSIS .exe on Windows,
AppImage and .deb on Linux, .dmg/.zip on macOS). A release build also bundles the
Python backend first (pnpm build:backend-runtime); without it the installer works only
next to a checkout. To try the packaged app without an installer:
pnpm build && pnpm --filter @horrible/desktop run package # apps/desktop/release/*-unpacked
pnpm smoke:desktop # drive it end to end
Backend on its own
pnpm dev already runs the backend; start it standalone only when iterating on Python:
uv run uvicorn backend.app:app --reload --reload-dir backend --reload-exclude "logs/*" --port 8000 # dev server
uv run pytest # backend tests
uv run ruff format . && uv run ruff check --fix . # format + lint Python
--reload-dir backend scopes the watcher to Python source only; --reload-exclude
additionally excludes logs/ (where backend.log lives) so writing a log line never
triggers a reload loop.
Checks
pnpm typecheck # all TS workspaces
pnpm lint # ESLint
pnpm format # Prettier (writes)
uv run pytest # backend tests
Scripts reference
Every script in the repo-root package.json:
| Script | Underlying command | Purpose |
|---|---|---|
pnpm dev | node scripts/dev.mjs | Full browser stack: FastAPI backend, Vite UI, and the game server (:9200) together (localhost:5173). --no-gameserver skips the last. |
pnpm dev:web | pnpm --filter @horrible/web dev | Frontend only (assumes a backend is already up). |
pnpm dev:lan | node scripts/dev.mjs --host 0.0.0.0 | Same as dev but bound to 0.0.0.0 for LAN / peer-fabric access. |
pnpm dev:desktop | node scripts/dev-desktop.mjs | Desktop layout (Vite + Electron); the shell supervises the backend. Binds 0.0.0.0 by default — --host 127.0.0.1 for local only. |
pnpm build | pnpm --filter @horrible/web build | Production web bundle. |
pnpm build:desktop | pnpm build && pnpm --filter @horrible/desktop dist | Desktop installers for this platform (electron-builder → apps/desktop/release/). |
pnpm smoke:desktop | node scripts/desktop-smoke.mjs | Launch the packaged desktop app and check it end to end (window, backend, CORS and /ws, shell commands, shutdown). |
pnpm build:icons | node scripts/build_icons.mjs | Regenerate app icons from source art. |
pnpm typecheck | pnpm -r typecheck | Typecheck every workspace package. |
pnpm lint | eslint . | Lint the whole repo. |
pnpm format | prettier --write . | Format the whole repo. |
Troubleshooting
- Vite proxy
ECONNRESET/ECONNREFUSED, or the backend aborts withOPENSSL_Uplink ... no OPENSSL_Applink(Windows). A MinGWlibcryptoonPATH(e.g.C:\msys64\mingw64\bin) can get loaded for TLS and crash the worker.backend/__init__.pystrips MinGW dirs from the processPATHat import, so the standard commands above work regardless of your shellPATH. - A dev port (
:5173/:8000/:9200) stays bound after an interrupted run (Windows).uvicorn --reloadrespawns workers, so an ungraceful stop can orphan one holding a port.pnpm devnow self-heals: it frees its own ports before starting and synchronously tree-kills + port-frees them on shutdown (scripts/dev.mjs), so a stale worker no longer cascades into "port in use" on the next run. A manually starteduv run uvicorn --reloadcan still orphan a worker — kill the whole process tree if a stale one holds the port. pnpm dev:desktopsays "Port 5173 is already in use", or an old backend still answers on :8000 (Linux). Earlier launchers stopped Electron by signalling its whole process group; Chromium then aborted ("GPU process isn't usable. Goodbye.") before it could stop the backend, and a closed terminal left Vite running. The launcher now signals Electron's main process alone and handles SIGHUP, and the backend exits by itself when the shell that spawned it is gone, however it went (backend/parent_watch.py). A process left over from before that still has to be stopped once — the launcher prints its pid.- Backend restarts with nothing edited ("♻️ backend\…_init_.py changed").
pnpm devdoes not useuvicorn --reload;scripts/dev.mjswatchesbackend/itself. On Windows, Node'sfs.watchreports a bare last-access-time update as a change, and NTFS keeps those on by default, so any process that read a backend file used to restart the backend (about 17 s of "Failed to fetch"). The watcher now restarts only when a file's modification time or size actually changed. To check it, set only the access time —(Get-Item <file>).LastAccessTime = Get-Date— and no restart should follow. A hand-runuvicorn --reloadstill needs--reload-dir backend --reload-exclude "logs/*", or it watcheslogs/backend.logand restarts on its own log writes. - Backend crashed mid-session. If it had been serving,
pnpm devrestarts it (2 s, then longer); only three quick crashes in a row leave it down until the next file change, and Vite stays up either way. A backend that never came up still stops the stack. Every line oflogs/backend.lognames its process ([pid]), and a native crash writesFatal Python errororWindows fatal exceptionwith every thread's stack into the same file. The log is rolled tobackend.log.1at startup once it passes 50 MB. - The dashboard blanks out and comes back while you use it (dev only), with
new dependencies optimized: … reloadingin the terminal. Vite reloads the whole page whenever it pre-bundles a dependency it did not find at startup. That only happens when its startup scan fails, and one unresolvable import in any page it scans is enough: the dev-onlyapps/web/operator-check.htmlimportsthree, whichapps/webdoes not depend on.optimizeDeps.entriesinapps/web/vite.config.tstherefore limits the scan toindex.html. If it comes back, runDEBUG=vite:deps pnpm dev:weband look forFailed to run dependency scan. - Desktop first build seems stuck. It's compiling Rust; give it a few minutes.
For how to verify a change in the running app, see the running-the-app workflow.