mirror of
https://github.com/tronbyt/server.git
synced 2026-10-16 04:06:41 +02:00
Ayush Soni
21031a1955
Build and test / Lint & Quality Checks (push) Waiting to run
Build and test / build-and-test (tronbyt-server-darwin-arm64, arm64, darwin, macos-26) (push) Waiting to run
Build and test / build-and-test (tronbyt-server-linux-amd64, amd64, linux, ubuntu-24.04) (push) Waiting to run
Build and test / build-and-test (tronbyt-server-linux-arm64, arm64, linux, ubuntu-24.04-arm) (push) Waiting to run
Build and test / build-and-test (tronbyt-server-windows-amd64.exe, amd64, windows, windows-2025) (push) Waiting to run
Create and publish a container image / build-and-push-image (push) Waiting to run
* feat: add opt-in community app stats managed by Niblet Admins can choose to share which library apps are installed on at least one enabled device, plus a rough device count, with Niblet Cloud (tronbyt-app-usage.v1). Off by default; chosen on the first-admin setup form, in a one-time prompt after updating, or in System Settings. - Reports are sent only when the app list or device range changes, at most every 6 hours; otherwise a weekly check-in without app data lets Cloud expire servers that are gone. - Failed sends back off from 1 hour, doubling to 24 hours, with jitter; the retry time is saved before networking so restarts cannot flood. - Cloud issues the token; a 401 forgets it and registers again. - Hosted servers prove their public hostname via a one-time challenge at /.well-known/niblet-reporter. - Opting out deletes everything shared and retries until confirmed. * refactor: address review feedback on community app stats - Never hold a lock across Niblet Cloud requests. An atomic flag keeps syncs from overlapping, and a consent change made during a sync is applied by a forced rerun, so saving the setting returns immediately. - Servers without devices send nothing until one is added; settings show "Contributing · starts when you add a device". - Share one Niblet Cloud client (reused connections) between install counts and stats, in niblet_client.go. - Move setSettings (now one transaction), localReturnPath and publicBaseURL to helpers.go. - Compute the retry backoff with a clamped shift. - Add doc comments and a NIBLET_CLOUD_URL entry to .env.example.
Tronbyt Server
The Tronbyt Server is a Go-based application designed to manage apps on Tronbyt devices locally, without relying on Tidbyt's backend servers. It offers a web UI for app discoverability and operates independently of cloud dependencies, ensuring continued functionality even if Tidbyt's servers are offline. The server also enables some APIs that were previously blocked by Tidbyt's servers, such as Surfline apps, and supports custom hardware.
However, there are some drawbacks, including the lack of a mobile app, slightly higher latency for notifications, and limited support for some built-in apps and apps relying on Tidbyt's cloud services for secrets.
Prerequisites for running Tronbyt Server:
- Docker and Docker Compose (optional but recommended) for containerized deployment.
- Homebrew for macOS and Linux bare-metal installations (provides pre-built binary).
- Go 1.26+ if building from source.
Supported Devices:
- Tidbyt Gen1 and Gen2
- Tronbyt S3 and S3 Wide
- MatrixPortal S3, MatrixPortal S3 Waveshare, MatrixPortal S3 Wide (128x64) and MatrixPortal S3 Square (64x64)
- Raspberry Pi (64x32), Raspberry Pi Wide (128x64) and Raspberry Pi Square (64x64) connected to matrix LED panels
- Pixoticker (limited memory, not recommended)
Developing additional clients for Tronbyt Server is straightforward: pull WebP images from the /next endpoint and loop the animation for the duration specified in the Tronbyt-Dwell-Secs response header. Display brightness can optionally be set using the Tronbyt-Brightness header (0-100).
Installation Methods:
- Docker: The recommended method uses Docker Compose with a configuration file. Video Tutorial : Raspberry Pi Setup with Docker
- Home Assistant: https://github.com/kaffolder7/ha-app-tronbyt-server
- Bare metal (Homebrew): Install using Homebrew:
brew install tronbyt-server - Bare metal (from source): Build from source using Go.
- RaspberryPI Install Script
curl -fsSL https://raw.githubusercontent.com/tronbyt/server-docker-compose/main/rpi_setup.sh | bash
Running the Application:
- For Docker installations, use
docker compose up -d. - For Homebrew installations:
brew services start tronbyt-server. - For native installations (from source):
go build -o tronbyt-server ./cmd/server && ./tronbyt-server - Access the web app at
http://localhost:8000.
CLI Commands
The tronbyt-server binary supports additional commands for administration:
-
reset-password <username> <new_password>: Resets the password for a specified user../tronbyt-server reset-password admin newsecretpassword -
health [url]: Performs a health check against the running server. Defaults tohttp://localhost:8000/health../tronbyt-server health ./tronbyt-server health https://your-tronbyt-server.com/health -
update-system-apps: Updates the system apps repo../tronbyt-server update-system-apps
Monitoring
/metrics: Exposes Prometheus-compatible metrics for monitoring the server's health and performance. This endpoint includes application-specific metrics (tronbyt_*for renders, device activity, HTTP requests, users/devices/apps counts), GORM database connection pool stats, and standard Go runtime metrics.curl http://localhost:8000/metrics/debug/pprof/: Exposes Go pprof endpoints whenENABLE_PPROF=trueis set. Disabled by default.
Quick Start Guide:
- Access the web app at
http://localhost:8000. - Add your Tronbyt as a device.
- Click "Firmware," enter WiFi credentials, and generate/download the firmware.
- Use the ESPHome firmware flasher to flash your Tidbyt into a Tronbyt.
- Add and configure an app via the built-in Pixlet interface.
- Save to see the app preview.
Ports: The web app is exposed on port 8000.
Updating:
- Docker containers:
docker compose pull && docker compose up -d.
Migration from v1.x: If you are upgrading from the Python version (v1.x) and using the default SQLite database:
- Ensure your old
usersdb.sqlitefile is in the data directory. If your Python installation had a separateusersvolume/directory (e.g., mounted at/app/usersin Docker), thisusersdirectory needs to be attached as a volume to the Go server's main data directory (e.g.,/app/data/usersor directly at/app/users) during the first migration run. After successful migration, this oldusersvolume can be safely detached and removed, as all its relevant contents will have been migrated to the newdatastructure. - Start the new server.
- The server will automatically detect the legacy database and migrate your users, devices, and apps to the new
tronbyt.dbformat. - The legacy database will be renamed to
usersdb.sqlite.bakafter successful migration.
Development:
- Clone the repository and use
docker compose -f docker-compose.dev.yaml up -d --buildfor Docker development. - For native development:
- Run directly:
go run ./cmd/server. - With live-reloading (using Air):
Run:
PRODUCTION=false go tool air
- Run directly:
Configuration:
The server can be configured via environment variables or .env file:
DB_DSN: Database connection string (default:data/tronbyt.db). Supports SQLite, PostgreSQL, and MySQL.DATA_DIR: Directory for data files (default:data).TRONBYT_HOST: Listen address (default: empty / all interfaces).TRONBYT_PORT: Listen port (default:8000).TRONBYT_UNIX_SOCKET: Path to Unix socket to listen on (optional).TRONBYT_SSL_KEYFILE&TRONBYT_SSL_CERTFILE: Paths to TLS key/cert for native HTTPS.TRONBYT_TRUSTED_PROXIES: Trusted proxy CIDR ranges (default:*).ENABLE_PPROF: Set to1to enable pprof routes at/debug/pprof/(default:0).ENABLE_USER_REGISTRATION: Allow open user registration (default:true).ENABLE_UPDATE_CHECKS: Check for new releases on startup (default:true).MAX_USERS: Maximum number of user accounts (default:0/ unlimited).SINGLE_USER_AUTO_LOGIN: Skip login when only one user exists (default:false).SYSTEM_APPS_REPO: Git repository URL for system apps (default:https://github.com/tronbyt/apps.git). End the URL with#branch-nameto use a branch other than the default.SYSTEM_APPS_AUTO_REFRESH: Initial default for refreshing the system apps repository every 12 hours (default:false). Administrators can change this under Settings → Content and Firmware; a saved web preference takes precedence on later starts.CUSTOM_APPS_AUTO_REFRESH: Automatically refresh every user's custom apps repository, every 12h (default:false).NIBLET_CLOUD_URL: Source of the install counts shown on system app cards, refreshed at most daily, and destination of the opt-in community app stats in System Settings, which are off by default (default:https://cloud.heyniblet.com). Set to an empty string to disable both.GITHUB_TOKEN: GitHub token for private app repositories (optional).REDIS_URL: Redis connection string for caching (optional).LOG_LEVEL: Logging verbosity:DEBUG,INFO,WARN,ERROR(default:INFO).
HTTPS (TLS):
- Can be achieved by configuring
TRONBYT_SSL_KEYFILEandTRONBYT_SSL_CERTFILE. - Or by fronting the service with a reverse proxy like Caddy (see
docker-compose.https.yaml). - After enabling HTTPS, configure the health check to use the corresponding URL, e.g.
test: ["CMD", "/app/tronbyt-server", "health", "https://tronbyt.example.com/health"].
Cache: By default, an in-memory cache is used. Redis can be configured via REDIS_URL for persistent caching across container restarts.