From 66d0d61c343a4ab53d1102462cb707bf7fc401ed Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Wed, 11 Mar 2026 09:39:59 -0700 Subject: [PATCH] Update documentation and remove postinstall script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README now includes full setup instructions, troubleshooting, account creation, and system apps fix. CLAUDE.md streamlined to codebase reference. postinstall.sh removed — binary auto-downloads via src/binary.ts on first run. Co-Authored-By: Claude Haiku 4.5 --- CLAUDE.md | 29 +++++------------------ README.md | 54 ++++++++++++++++++++++++++++++++---------- package.json | 5 ++-- scripts/postinstall.sh | 17 ------------- 4 files changed, 49 insertions(+), 56 deletions(-) delete mode 100755 scripts/postinstall.sh diff --git a/CLAUDE.md b/CLAUDE.md index 5fc36a8..6077bdc 100644 --- a/CLAUDE.md +++ b/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 -``` -Tidbyt device → tronbyt.toes.local → toes → Bun (PORT) → Go binary (unix socket) -``` - -- `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 +- `src/server.ts` — entry point, creates Bun server, calls spawn +- `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) ## 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//next -``` diff --git a/README.md b/README.md index 1ba9816..b4ab0cb 100644 --- a/README.md +++ b/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 -- At runtime, the app looks for a binary in `bin/` matching the current platform (`tronbyt-server-{darwin|linux}-{arm64|amd64}`) -- If the binary isn't found, the app logs an error with the download URL and the expected filename -- The binary runs as a child process with `stdout`/`stderr` inherited (logs show up in toes) +- On first start, `src/binary.ts` downloads the platform-appropriate binary (`tronbyt-server-{darwin|linux}-{arm64|amd64}`) into `bin/` +- The binary runs as a child process listening on TCP port 8000, with `stdout`/`stderr` inherited (logs show up in toes) +- `src/proxy.ts` forwards all HTTP and WebSocket traffic from the toes-assigned PORT to the Go binary on port 8000 - 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/`. diff --git a/package.json b/package.json index dfd3242..c7250ff 100644 --- a/package.json +++ b/package.json @@ -6,8 +6,7 @@ "scripts": { "toes": "bun run --watch src/server.ts", "start": "bun toes", - "dev": "bun run --hot src/server.ts", - "postinstall": "bash scripts/postinstall.sh" + "dev": "bun run --hot src/server.ts" }, "toes": { "icon": "🖥️" @@ -19,4 +18,4 @@ "typescript": "^5.9.2" }, "dependencies": {} -} +} \ No newline at end of file diff --git a/scripts/postinstall.sh b/scripts/postinstall.sh deleted file mode 100755 index 8e10256..0000000 --- a/scripts/postinstall.sh +++ /dev/null @@ -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" -- 2.50.1