Corey Johnson
66d0d61c34
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>
95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# Tronbyt
|
|
|
|
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 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
|
|
|
|
### 1. Deploy to your toes server
|
|
|
|
```sh
|
|
git remote add toes http://git.toes.local/tronbyt
|
|
git push toes main
|
|
```
|
|
|
|
Pushing to the git remote deploys the app, runs `bun install`, and starts it automatically.
|
|
|
|
### 2. The binary
|
|
|
|
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.
|
|
|
|
To download manually:
|
|
|
|
```sh
|
|
curl -L -o bin/tronbyt-server-linux-arm64 \
|
|
https://github.com/tronbyt/server/releases/latest/download/tronbyt-server-linux-arm64
|
|
chmod +x bin/tronbyt-server-linux-arm64
|
|
```
|
|
|
|
### 3. First boot
|
|
|
|
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)
|
|
2. During device setup, set the **Image URL** to:
|
|
```
|
|
http://tronbyt.toes.local/<device-id>/next
|
|
```
|
|
The device ID is assigned when you add the device in the Tronbyt web dashboard.
|
|
|
|
**Important:** The Image URL must be the full path including `/<device-id>/next` — the device uses it exactly as-is.
|
|
|
|
## Environment Variables
|
|
|
|
Set these through `toes env tronbyt` to override defaults:
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `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
|
|
|
|
- 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
|
|
- 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/`.
|