Update documentation and remove postinstall script
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 <noreply@anthropic.com>
This commit is contained in:
parent
a56dfdc422
commit
66d0d61c34
29
CLAUDE.md
29
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/<device-id>/next
|
||||
```
|
||||
|
|
|
|||
54
README.md
54
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/`.
|
||||
|
|
|
|||
|
|
@ -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": "🖥️"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
Loading…
Reference in New Issue
Block a user