Skip to main content

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.

Kept in sync with package.json

The 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​

ToolVersionNotes
Node.jsLTS (≥ 20)Runtime for pnpm and Vite.
pnpm10.28.2Pinned via packageManager. Easiest: corepack enable (uses the pinned version automatically).
Python≥ 3.12The backend (requires-python = ">=3.12").
uvlatestPython package/venv manager — install guide. The backend is managed with uv, never pip.
Electronfrom pnpm installDesktop 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 dev automatically loads a .env file at the repository root if one is present, allowing you to configure local environment variables (such as GAMES_GOOGLE_CLIENT_ID or custom port overrides) for the development processes.
  • pnpm dev:web — UI only, when a backend is already running.
  • pnpm dev:lan — bind both servers to 0.0.0.0 so other machines can reach this node (needed for the peer fabric / collaboration).
  • pnpm dev --no-gameserver (or HORRIBLE_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 into pnpm dev is purely a local-dev convenience; if :9200 is 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.

Reusing an already-running backend

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:

ScriptUnderlying commandPurpose
pnpm devnode scripts/dev.mjsFull browser stack: FastAPI backend, Vite UI, and the game server (:9200) together (localhost:5173). --no-gameserver skips the last.
pnpm dev:webpnpm --filter @horrible/web devFrontend only (assumes a backend is already up).
pnpm dev:lannode scripts/dev.mjs --host 0.0.0.0Same as dev but bound to 0.0.0.0 for LAN / peer-fabric access.
pnpm dev:desktopnode scripts/dev-desktop.mjsDesktop layout (Vite + Electron); the shell supervises the backend. Binds 0.0.0.0 by default — --host 127.0.0.1 for local only.
pnpm buildpnpm --filter @horrible/web buildProduction web bundle.
pnpm build:desktoppnpm build && pnpm --filter @horrible/desktop distDesktop installers for this platform (electron-builder → apps/desktop/release/).
pnpm smoke:desktopnode scripts/desktop-smoke.mjsLaunch the packaged desktop app and check it end to end (window, backend, CORS and /ws, shell commands, shutdown).
pnpm build:iconsnode scripts/build_icons.mjsRegenerate app icons from source art.
pnpm typecheckpnpm -r typecheckTypecheck every workspace package.
pnpm linteslint .Lint the whole repo.
pnpm formatprettier --write .Format the whole repo.

Troubleshooting​

  • Vite proxy ECONNRESET / ECONNREFUSED, or the backend aborts with OPENSSL_Uplink ... no OPENSSL_Applink (Windows). A MinGW libcrypto on PATH (e.g. C:\msys64\mingw64\bin) can get loaded for TLS and crash the worker. backend/__init__.py strips MinGW dirs from the process PATH at import, so the standard commands above work regardless of your shell PATH.
  • A dev port (:5173/:8000/:9200) stays bound after an interrupted run (Windows). uvicorn --reload respawns workers, so an ungraceful stop can orphan one holding a port. pnpm dev now 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 started uv run uvicorn --reload can still orphan a worker — kill the whole process tree if a stale one holds the port.
  • pnpm dev:desktop says "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 dev does not use uvicorn --reload; scripts/dev.mjs watches backend/ itself. On Windows, Node's fs.watch reports 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-run uvicorn --reload still needs --reload-dir backend --reload-exclude "logs/*", or it watches logs/backend.log and restarts on its own log writes.
  • Backend crashed mid-session. If it had been serving, pnpm dev restarts 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 of logs/backend.log names its process ([pid]), and a native crash writes Fatal Python error or Windows fatal exception with every thread's stack into the same file. The log is rolled to backend.log.1 at startup once it passes 50 MB.
  • The dashboard blanks out and comes back while you use it (dev only), with new dependencies optimized: … reloading in 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-only apps/web/operator-check.html imports three, which apps/web does not depend on. optimizeDeps.entries in apps/web/vite.config.ts therefore limits the scan to index.html. If it comes back, run DEBUG=vite:deps pnpm dev:web and look for Failed 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.