Merge pull request 'Update docs and remove postinstall script' (#2) from probablycorey/browser-automation into main

Reviewed-on: #2

CLAUDE.md

@@ -2,24 +2,14 @@
 
 This is a [toes](/Users/corey/code/toes) app. See the [toes CLAUDE.md](/Users/corey/code/toes/CLAUDE.md) for the framework docs.
 
-Wraps the Tronbyt Go server (self-hosted Tidbyt replacement) as a toes-managed subprocess. Bun proxies all HTTP and WebSocket traffic to the Go binary over a unix socket.
+Wraps the Tronbyt Go server (self-hosted Tidbyt replacement) as a toes-managed subprocess. Bun proxies all HTTP and WebSocket traffic to the Go binary.
 
-## How It Works
+## Key Files
 
-```
+- `src/server.ts` — entry point, creates Bun server, calls spawn
-Tidbyt device → tronbyt.toes.local → toes → Bun (PORT) → Go binary (unix socket)
+- `src/proxy.ts` — HTTP + WebSocket proxy from Bun to Go binary on port 8000
-```
+- `src/binary.ts` — Go binary lifecycle: download, spawn, health checks, shutdown
-
+- `bin/` — Go binary (gitignored, auto-downloaded per-platform)
-- `src/server/index.tsx` — spawns Go binary, proxies HTTP + WebSocket, health checks
-- `bin/` — pre-built Go binary (gitignored, per-platform)
-- No UI of its own — Go server serves its own web dashboard
-
-## Setup
-
-1. Download the binary for your platform from https://github.com/tronbyt/server/releases
-2. Place it in `bin/` (e.g. `bin/tronbyt-server-darwin-arm64`)
-3. `chmod +x bin/tronbyt-server-*`
-4. On macOS: System Settings → Privacy & Security → Allow Anyway
 
 ## Env Vars
 
@@ -29,10 +19,3 @@ Tronbyt-specific vars (set via toes env config):
 - `PRODUCTION` — `true` enables firmware downloads and system apps (default)
 - `SINGLE_USER_AUTO_LOGIN` — `true` for home network (default)
 - `SYSTEM_APPS_AUTO_REFRESH` — `true` to keep community apps updated (default)
-
-## Device Config
-
-Set the Tidbyt Image URL to:
-```
-http://tronbyt.toes.local/<device-id>/next
-```

README.md

@@ -2,7 +2,11 @@
 
 Run a [Tronbyt](https://github.com/tronbyt/server) server as a toes app. Tronbyt is a self-hosted replacement for Tidbyt's cloud — it renders Starlark apps into WebP frames and pushes them to Tidbyt LED displays over your local network.
 
-This app spawns the pre-built Tronbyt Go binary as a subprocess and proxies all traffic (HTTP + WebSocket) to it over a unix socket. The Go server handles everything — web dashboard, device connections, app rendering. Bun just sits in front and makes it a good toes citizen.
+This app spawns the Tronbyt Go binary as a subprocess and proxies all traffic (HTTP + WebSocket) through Bun. The Go server handles everything — web dashboard, device connections, app rendering. Bun sits in front and makes it a good toes citizen.
+
+```
+Tidbyt device → tronbyt.toes.local → toes (port 80) → Bun (PORT) → Go binary (port 8000)
+```
 
 ## Install
 
@@ -13,13 +17,13 @@ git remote add toes http://git.toes.local/tronbyt
 git push toes main
 ```
 
-Pushing to the git tool deploys the app, runs `bun install` (which downloads the binary), and starts it automatically.
+Pushing to the git remote deploys the app, runs `bun install`, and starts it automatically.
 
 ### 2. The binary
 
-The Tronbyt Go binary is downloaded automatically during `bun install` via the postinstall script. It assumes you're running on a Raspberry Pi (linux-arm64) — which is what toes is designed for.
+The Go binary auto-downloads from GitHub releases on first start if it's not already present. It's gitignored since it's platform-specific and ~50MB.
 
-The binary is gitignored since it's platform-specific and ~50MB. If you need to re-download it or the postinstall didn't run, you can grab it manually:
+To download manually:
 
 ```sh
 curl -L -o bin/tronbyt-server-linux-arm64 \
@@ -27,14 +31,16 @@ curl -L -o bin/tronbyt-server-linux-arm64 \
 chmod +x bin/tronbyt-server-linux-arm64
 ```
 
-If the binary already exists in `bin/`, the postinstall skips the download.
-
 ### 3. First boot
 
-On first start, the server clones the [community Starlark apps repo](https://github.com/tronbyt/apps) (~15 seconds). With `PRODUCTION=false` (the default), firmware downloads are skipped.
+On first start, the Go server clones the [community Starlark apps repo](https://github.com/tronbyt/apps) into `DATA_DIR/system-apps/`. This can take a while on a Pi. With `PRODUCTION=true` (the default), it also downloads firmware for OTA device updates.
 
 All data (SQLite DB, cloned apps, firmware) is stored in the app's `DATA_DIR`, which persists across restarts and deploys.
 
+### 4. Create an account
+
+Visit `http://tronbyt.toes.local/auth/register` to create your user account, then log in and click "New Tronbyt" to add a device.
+
 ## Configure your Tidbyt
 
 1. Flash your Tidbyt with [Tronbyt firmware](https://github.com/tronbyt/server/releases) (see firmware flashing docs)
@@ -52,15 +58,37 @@ Set these through `toes env tronbyt` to override defaults:
 
 | Variable | Default | Description |
 |---|---|---|
-| `PRODUCTION` | `false` | Set `true` to enable firmware downloads for OTA updates |
+| `PRODUCTION` | `true` | Enables firmware downloads for OTA updates |
 | `SINGLE_USER_AUTO_LOGIN` | `true` | Auto-login without password (good for home network) |
 | `SYSTEM_APPS_AUTO_REFRESH` | `true` | Auto-refresh community apps repo every 12h |
 
 ## How the binary is managed
 
-- `bun install` runs `scripts/postinstall.sh`, which downloads `tronbyt-server-linux-arm64` into `bin/` if it doesn't already exist
+- On first start, `src/binary.ts` downloads the platform-appropriate binary (`tronbyt-server-{darwin|linux}-{arm64|amd64}`) into `bin/`
-- At runtime, the app looks for a binary in `bin/` matching the current platform (`tronbyt-server-{darwin|linux}-{arm64|amd64}`)
+- The binary runs as a child process listening on TCP port 8000, with `stdout`/`stderr` inherited (logs show up in toes)
-- If the binary isn't found, the app logs an error with the download URL and the expected filename
+- `src/proxy.ts` forwards all HTTP and WebSocket traffic from the toes-assigned PORT to the Go binary on port 8000
-- The binary runs as a child process with `stdout`/`stderr` inherited (logs show up in toes)
 - On shutdown (SIGTERM from toes), the app forwards SIGTERM to the Go process
-- The unix socket is created in `DATA_DIR/tronbyt.sock` and cleaned up on startup to handle stale sockets from crashes
+- Health checks poll `http://127.0.0.1:8000/health` — the `/ok` endpoint reports "starting" until the Go server is ready
+
+## Troubleshooting
+
+### Add App page is empty (no community apps)
+
+The Go server clones `https://github.com/tronbyt/apps.git` into `DATA_DIR/system-apps/` on first boot. If that clone fails (network issue, permissions), you get 0 apps and the 12h auto-refresh won't fix a broken git state. Fix it manually:
+
+```bash
+cd /home/toes/data/toes/tronbyt/system-apps/
+git fetch origin '+refs/heads/*:refs/remotes/origin/*'
+git checkout -b main origin/main   # or: git reset --hard origin/main
+chown -R toes:toes .                # must be owned by the toes user
+```
+
+Then restart tronbyt: `POST http://toes.local/api/apps/tronbyt/restart`, then `POST http://toes.local/api/apps/tronbyt/start`.
+
+### Go binary not starting
+
+Check logs: `sudo journalctl -u toes | grep tronbyt`. Verify port 8000 is bound: `ss -tlnp | grep 8000`. The binary can take 30+ seconds to start when loading ~1000 community apps.
+
+### File permission errors
+
+Everything under `DATA_DIR` must be owned by the `toes` user. Fix with `sudo chown -R toes:toes /home/toes/data/toes/tronbyt/`.

package.json

@@ -6,8 +6,7 @@
   "scripts": {
     "toes": "bun run --watch src/server.ts",
     "start": "bun toes",
-    "dev": "bun run --hot src/server.ts",
+    "dev": "bun run --hot src/server.ts"
-    "postinstall": "bash scripts/postinstall.sh"
   },
   "toes": {
     "icon": "🖥️"
@@ -19,4 +18,4 @@
     "typescript": "^5.9.2"
   },
   "dependencies": {}
-}
+}

scripts/postinstall.sh

@@ -1,17 +0,0 @@
-#!/bin/bash
-set -e
-
-BIN_DIR="$(dirname "$0")/../bin"
-BINARY="$BIN_DIR/tronbyt-server-linux-arm64"
-URL="https://github.com/tronbyt/server/releases/latest/download/tronbyt-server-linux-arm64"
-
-if [ -f "$BINARY" ]; then
-  echo "tronbyt binary already exists, skipping download"
-  exit 0
-fi
-
-echo "Downloading tronbyt server binary..."
-mkdir -p "$BIN_DIR"
-curl -L -o "$BINARY" "$URL"
-chmod +x "$BINARY"
-echo "Done"