---
name: run-server
description: Build, run, and drive the espresso_frame FastAPI server (server/) -- start it against a scratch DB, browser-test its UI, run its pytest suite. Use when asked to start the server, take a screenshot of a frame page, click through the web UI, or verify a server/UI change actually works.
---

The espresso_frame server is a FastAPI app (`app.main:app`) with a
server-rendered Jinja UI. For agent/automated use it's driven by a
Playwright REPL at `.claude/skills/run-server/driver.py`, run under
tmux -- `chromium-cli` isn't available in this container, so this
driver replaces it (same command vocabulary: nav/wait-for/click/fill/
screenshot/eval/console-errors).

This container ships with **no Python, Node, Docker, or browser, and
no sudo**. `setup.sh` bootstraps everything non-root; it's the bulk of
what makes this skill non-obvious. Run it once per fresh container.

Commands below (`setup.sh`, `start-server.sh`, `stop-server.sh`,
`env.sh`, `driver.py`) are invoked from the **repo root** via their
`.claude/skills/run-server/` path -- the scripts `cd` into `server/`
themselves. Anything under `.venv/` (the venv itself, `pytest`,
`uvicorn`) lives inside `server/`, so those commands need `server/`
prefixed or `cd server` first.

## Prerequisites

None to install manually -- `setup.sh` does it all without root, using
only `curl`/`apt-get download`/`dpkg-deb -x` (never `apt-get install`,
which needs root). It downloads ~450MB total (Python, Chromium, tmux,
shared libs) on first run.

```bash
bash .claude/skills/run-server/setup.sh
```

Re-running is safe and fast -- every step checks whether it already
happened (venv exists? chromium downloaded? libs extracted? tmux
present?) before doing any work.

This creates:
- `.venv/` -- Python 3.12 + `requirements.txt` + `playwright`, via `uv`
  (a static Rust binary that fetches its own Python -- no compiler
  needed, install via `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- `~/.cache/ms-playwright/` -- Chromium (full `chrome` + headless-shell)
- `/tmp/run-server-chromium-deps/` -- Chromium's + tmux's shared libs
  and fonts, extracted (not installed) from `.deb` files
- `.claude/skills/run-server/env.sh` -- the `PATH`/`LD_LIBRARY_PATH`/
  `FONTCONFIG_PATH`/`RUN_SERVER_CHROME_BIN` exports the driver needs
  (gitignored -- host-specific `/tmp` paths, regenerated by setup.sh)

## Run (agent path)

**1. Start the server** against a scratch DB (never the real
deployment's data -- see `CLAUDE.md`):

```bash
bash .claude/skills/run-server/start-server.sh
# -> server PID <pid> up on http://127.0.0.1:8420 (log: /tmp/run-server-scratch/server.log)
```

Optional args: `start-server.sh [scratch-dir] [port]` (defaults
`/tmp/run-server-scratch` / `8420`).

**2. Drive it**, wrapped in tmux so you can send one command at a time
and read the response before sending the next. `tmux` itself was
extracted the same non-root way as Chromium's libs (see Prerequisites)
and needs `LD_LIBRARY_PATH` set in *this* shell too, not just inside
the pane -- source `env.sh` before the first `tmux` call:

```bash
source .claude/skills/run-server/env.sh
tmux new-session -d -s runserver -x 200 -y 50
tmux send-keys -t runserver \
  'source .claude/skills/run-server/env.sh && server/.venv/bin/python .claude/skills/run-server/driver.py' Enter
timeout 20 bash -c 'until tmux capture-pane -t runserver -p | grep -q "driver>"; do sleep 0.3; done'

# Every fresh scratch DB starts with no users -- bootstrap-admin
# completes first-run /setup and logs in (see Commands table):
tmux send-keys -t runserver 'bootstrap-admin' Enter
timeout 15 bash -c 'until tmux capture-pane -t runserver -p | grep -q "bootstrapped admin"; do sleep 0.3; done'

tmux send-keys -t runserver 'nav /frames/1/config' Enter
tmux send-keys -t runserver 'wait-for #frame-preview-thumb' Enter
tmux send-keys -t runserver 'screenshot before' Enter
tmux capture-pane -t runserver -p
```

Poll for a specific marker between `send-keys` and `capture-pane`
(`driver>`, `bootstrapped admin`, `screenshot:`, ...) rather than a
fixed `sleep` -- it's faster and fails loudly instead of capturing a
half-rendered screen. Give each poll its own `timeout` (~15-20s); don't
chain many polling loops inside one shell invocation -- see Gotchas.

Screenshots land in `/tmp/run-server-shots/` (override:
`SCREENSHOT_DIR`). **Actually look at them** -- a blank or error-page
screenshot is a failure to launch, not success.

**Test every UI change at both a desktop and a mobile viewport.** The
driver defaults to a desktop size (1280x900); switch with `viewport`.
The app's mobile breakpoint is 860px (`theme.css`) -- below that the
sidebar goes off-canvas behind a hamburger (`.mobile-bar`). A page that
looks right at 1280px can still overflow, overlap the mobile bar, or
mis-center a `<dialog>` at phone widths -- screenshot both:

```bash
tmux send-keys -t runserver 'viewport 1280 900' Enter   # desktop (also the default)
tmux send-keys -t runserver 'screenshot desktop-x' Enter
tmux send-keys -t runserver 'viewport 390 844' Enter     # iPhone-ish mobile width
tmux send-keys -t runserver 'screenshot mobile-x' Enter
```

### Driver commands

| command | what it does |
|---|---|
| `nav <path-or-url>` | navigate (relative paths resolve against `http://127.0.0.1:8420`, override with `RUN_SERVER_BASE_URL`) |
| `wait-for <selector>` | wait up to 10s for a selector (plain CSS -- see Gotchas for attribute selectors) |
| `click <selector>` | click an element |
| `fill <selector> <value>` | fill an input |
| `press <key>` | keyboard press (e.g. `Enter`) |
| `screenshot [name]` | → `/tmp/run-server-shots/<name>.png` |
| `eval <js>` | evaluate JS in the page, prints JSON |
| `console-errors` | prints all captured console/page errors as a JSON array |
| `viewport [w] [h]` | resize the viewport, default `390 844` -- use `1280 900` for desktop (see Gotchas re: real touch input) |
| `is-open <dialog-selector>` | prints `true`/`false` for a `<dialog>` element's `.open` -- use this instead of `wait-for sel[open]` |
| `bootstrap-admin [user] [pass]` | completes first-run `/setup` (defaults `admin`/`testpassword123`); links frame #1 and logs in |
| `quit` | closes the browser, exits the driver |

**3. Stop the server** when done:

```bash
bash .claude/skills/run-server/stop-server.sh
tmux kill-session -t runserver
```

## Run (human path)

```bash
cd server
DATABASE_URL="sqlite:////tmp/dev.db" CONFIG_PATH="/tmp/dev-config.json" \
  .venv/bin/uvicorn app.main:app --reload --port 8420
```

Open `http://localhost:8420` in a real browser. `start.sh` (the Docker
entrypoint) is not this -- it also launches the Node whiteboard
render-service sidecar, which needs Node (not installed here) and
isn't needed for most UI testing.

## Test

```bash
cd server && .venv/bin/pytest
```

Uses its own tempfile SQLite per run (`tests/conftest.py`) -- no setup
needed beyond the venv.

---

## Gotchas

- **`viewport` only resizes the window -- it does not emulate touch
  input.** `click` still dispatches a mouse click, not a tap; there's
  no touch-delay, no `:hover`-stickiness-after-tap, no `hasTouch`
  context. It catches real bugs (layout overflow, off-canvas sidebar,
  a `<dialog>` mis-centering at phone widths) but won't catch anything
  that's specifically a touch-vs-mouse event difference. Good enough
  for CSS/layout verification; not a substitute for testing on an
  actual phone if a change touches touch-specific interaction.

- **`chrome-headless-shell` (Playwright's default headless target)
  crashes on basic calls in this container**, e.g. `page.set_content()`
  returns `TargetClosedError`, even after every `ldd`-reported missing
  library is resolved. The full `chrome` binary (`chromium-*/chrome-linux64/chrome`)
  + `--no-sandbox` is stable; `driver.py` and `setup.sh` both use it,
  not the headless-shell default.

- **Missing fonts silently break `fill()`, not just rendering.** Before
  `fontconfig`/`libfontconfig1` were extracted and `fonts.conf` pointed
  at the extracted font dir, `page.fill()` ran with no error but left
  inputs empty (`input_value()` returned `""`), and all text rendered
  invisible in screenshots. It looks like a scripting bug, not a
  missing-lib problem -- if `fill` silently no-ops, suspect fonts
  before suspecting the selector or a race.

- **No `apt-get install` / `playwright install-deps` (no root) and no
  `apt-get update` into the real `/var/lib/apt/lists` (root-owned).**
  Worked around by redirecting apt's state dirs to a scratch,
  user-writable path (`-o Dir::State::Lists=... -o Dir::Cache=...`),
  which makes plain `update` and `install --download-only --print-uris`
  work as a non-root user; then `dpkg-deb -x <deb> <root>` (extract,
  not install) needs no root either. `setup.sh` does this for
  Chromium's deps *and* for `tmux` itself, which also isn't
  preinstalled.

- **`wait-for` with an attribute selector like `#frame-preview-dialog[open]`
  is unreliable through `tmux send-keys`** -- shell/tmux escaping of
  `[`/`]` easily mangles it (seen: a real 10s Playwright timeout from a
  garbled selector, not a fast failure). Use the app-specific `is-open
  <selector>` command instead of `wait-for sel[open]` to check a
  `<dialog>`'s open state.

- **Don't chain many `tmux send-keys` + polling-`timeout` loops inside
  one shell invocation.** Each poll can legitimately take up to its own
  timeout (e.g. 15s) if a selector is wrong; five or six chained in one
  command can add up past this tool's own command timeout even though
  each individual step is fine. Send one or two commands per shell
  call and check the pane before continuing.

- **A crashed `chrome-headless-shell` process can leave a large core
  dump file** (`server/core`, ~170MB, from the crash described above)
  if core dumps are enabled. It's not part of the app -- delete it, and
  use full `chrome` (as `driver.py` does) to avoid triggering it again.

## Troubleshooting

- **`error while loading shared libraries: libglib-2.0.so.0` (or similar)
  when launching Chromium directly**: `LD_LIBRARY_PATH` isn't set --
  source `.claude/skills/run-server/env.sh` first, or run through
  `driver.py`, which reads `RUN_SERVER_CHROME_BIN` from it.
- **`fc-list` prints nothing after extracting fonts**: `fonts.conf`'s
  `<dir>` entries still point at the real (unpopulated) `/usr/share/fonts`.
  `setup.sh` patches this with `sed`; if you extracted packages by hand,
  do the same.
- **`E: Could not open lock file ... Permission denied` from `apt-get`**:
  you're missing the `-o Dir::State::Lists=... -o Dir::Cache=...`
  overrides -- plain `apt-get update`/`install` always needs root here.
- **`tmux: command not found`**: not preinstalled and no sudo; run
  `setup.sh`, which fetches it the same non-root way as Chromium's libs.
- **`tmux: error while loading shared libraries: libutempter.so.0`**:
  you sourced `env.sh` inside the driver's tmux pane but not in the
  shell that *invokes* `tmux` itself -- `tmux` was extracted from the
  same non-root `.deb` set as Chromium and needs `LD_LIBRARY_PATH` too.
  `source .claude/skills/run-server/env.sh` before the first `tmux`
  command, not just inside `send-keys`.
