{"id":35473566,"url":"https://github.com/tronbyt/server","last_synced_at":"2026-05-24T06:01:12.805Z","repository":{"id":174822242,"uuid":"651856117","full_name":"tronbyt/server","owner":"tronbyt","description":"Manage your apps on your Tronbyt (flashed Tidbyt) completely locally without relying on the backend servers operated by Tidbyt.","archived":false,"fork":false,"pushed_at":"2026-05-16T08:14:04.000Z","size":55319,"stargazers_count":193,"open_issues_count":6,"forks_count":47,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-05-16T10:29:42.846Z","etag":null,"topics":["go","golang","gorm","tidbyt","tronbyt"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tronbyt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-06-10T09:56:40.000Z","updated_at":"2026-05-16T08:14:01.000Z","dependencies_parsed_at":"2023-07-09T17:33:16.717Z","dependency_job_id":"51eed471-7b65-465d-b1f5-9db609931d58","html_url":"https://github.com/tronbyt/server","commit_stats":null,"previous_names":["tavdog/tidbyt-manager","tavdog/tronbyt-server","tronbyt/server"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/tronbyt/server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tronbyt%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tronbyt%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tronbyt%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tronbyt%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tronbyt","download_url":"https://codeload.github.com/tronbyt/server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tronbyt%2Fserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33423284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","gorm","tidbyt","tronbyt"],"created_at":"2026-01-03T11:26:34.175Z","updated_at":"2026-05-24T06:01:12.798Z","avatar_url":"https://github.com/tronbyt.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tronbyt Server\n[Tronbyt Demo](https://tronbyt.clodhost.com/auth/register)\n\nThe 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.\n\nHowever, 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.\n\n**Prerequisites for running Tronbyt Server:**\n*   **Docker** and **Docker Compose** (optional but recommended) for containerized deployment.\n*   **Homebrew** for macOS and Linux bare-metal installations (provides pre-built binary).\n*   **Go 1.26+** if building from source.\n\n**Supported Devices:**\n*   Tidbyt Gen1 and Gen2\n*   Tronbyt S3 and S3 Wide\n*   MatrixPortal S3 and MatrixPortal S3 Waveshare\n*   Raspberry Pi (64x32) and Raspberry Pi Wide (128x64) connected to matrix LED panels\n*   Pixoticker (limited memory, not recommended)\n\nDeveloping 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).\n\n**Installation Methods:**\n*   **Docker:** The recommended method uses Docker Compose with a configuration file. Video Tutorial : [Raspberry Pi Setup with Docker](https://youtu.be/UeHzD0uFxRo)\n*   **Home Assistant:** https://github.com/kaffolder7/ha-app-tronbyt-server\n*   **Bare metal (Homebrew):** Install using Homebrew:\n    ```bash\n    brew install tronbyt-server\n    ```\n*   **Bare metal (from source):** Build from source using Go.\n\n**Running the Application:**\n*   For Docker installations, use `docker compose up -d`.\n*   For Homebrew installations: `brew services start tronbyt-server`.\n*   For native installations (from source): `go build -o tronbyt-server ./cmd/server \u0026\u0026 ./tronbyt-server`\n*   Access the web app at `http://localhost:8000`.\n\n### CLI Commands\n\nThe `tronbyt-server` binary supports additional commands for administration:\n\n*   **`reset-password \u003cusername\u003e \u003cnew_password\u003e`**: Resets the password for a specified user.\n    ```bash\n    ./tronbyt-server reset-password admin newsecretpassword\n    ```\n\n*   **`health [url]`**: Performs a health check against the running server. Defaults to `http://localhost:8000/health`.\n    ```bash\n    ./tronbyt-server health\n    ./tronbyt-server health https://your-tronbyt-server.com/health\n    ```\n\n*   **`update-system-apps`**: Updates the system apps repo.\n    ```bash\n    ./tronbyt-server update-system-apps\n    ```\n\n### Monitoring\n\n*   **`/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.\n    ```bash\n    curl http://localhost:8000/metrics\n    ```\n*   **`/debug/pprof/`**: Exposes Go pprof endpoints when `ENABLE_PPROF=true` is set. Disabled by default.\n\n**Quick Start Guide:**\n1.  Access the web app at `http://localhost:8000`.\n2.  Add your Tronbyt as a device.\n3.  Click \"Firmware,\" enter WiFi credentials, and generate/download the firmware.\n4.  Use the ESPHome firmware flasher to flash your Tidbyt into a Tronbyt.\n5.  Add and configure an app via the built-in Pixlet interface.\n6.  Save to see the app preview.\n\n**Ports:** The web app is exposed on port `8000`.\n\n**Updating:**\n*   Docker containers: `docker compose pull \u0026\u0026 docker compose up -d`.\n\n**Migration from v1.x:**\nIf you are upgrading from the Python version (v1.x) and using the default SQLite database:\n1.  Ensure your old `usersdb.sqlite` file is in the data directory. If your Python installation had a separate `users` volume/directory (e.g., mounted at `/app/users` in Docker), this `users` directory needs to be attached as a volume to the Go server's main data directory (e.g., `/app/data/users` or directly at `/app/users`) during the first migration run. After successful migration, this old `users` volume can be safely detached and removed, as all its relevant contents will have been migrated to the new `data` structure.\n2.  Start the new server.\n3.  The server will automatically detect the legacy database and migrate your users, devices, and apps to the new `tronbyt.db` format.\n4.  The legacy database will be renamed to `usersdb.sqlite.bak` after successful migration.\n\n**Development:**\n*   Clone the repository and use `docker compose -f docker-compose.dev.yaml up -d --build` for Docker development.\n*   For native development:\n    *   Run directly: `go run ./cmd/server`.\n    *   With live-reloading (using [Air](https://github.com/air-verse/air)):\n        Run: `PRODUCTION=false go tool air`\n\n**Configuration:**\n\nThe server can be configured via environment variables or `.env` file:\n*   `DB_DSN`: Database connection string (default: `data/tronbyt.db`). Supports SQLite, PostgreSQL, and MySQL.\n*   `DATA_DIR`: Directory for data files (default: `data`).\n*   `TRONBYT_HOST`: Listen address (default: empty / all interfaces).\n*   `TRONBYT_PORT`: Listen port (default: `8000`).\n*   `TRONBYT_UNIX_SOCKET`: Path to Unix socket to listen on (optional).\n*   `TRONBYT_SSL_KEYFILE` \u0026 `TRONBYT_SSL_CERTFILE`: Paths to TLS key/cert for native HTTPS.\n*   `TRONBYT_TRUSTED_PROXIES`: Trusted proxy CIDR ranges (default: `*`).\n*   `ENABLE_PPROF`: Set to `1` to enable pprof routes at `/debug/pprof/` (default: `0`).\n*   `ENABLE_USER_REGISTRATION`: Allow open user registration (default: `true`).\n*   `ENABLE_UPDATE_CHECKS`: Check for new releases on startup (default: `true`).\n*   `MAX_USERS`: Maximum number of user accounts (default: `0` / unlimited).\n*   `SINGLE_USER_AUTO_LOGIN`: Skip login when only one user exists (default: `false`).\n*   `SYSTEM_APPS_REPO`: Git repository URL for system apps (default: `https://github.com/tronbyt/apps.git`).\n*   `SYSTEM_APPS_AUTO_REFRESH`: Automatically refresh the system apps repository (default: `false`).\n*   `GITHUB_TOKEN`: GitHub token for private app repositories (optional).\n*   `REDIS_URL`: Redis connection string for caching (optional).\n*   `LOG_LEVEL`: Logging verbosity: `DEBUG`, `INFO`, `WARN`, `ERROR` (default: `INFO`).\n\n**HTTPS (TLS):**\n*   Can be achieved by configuring `TRONBYT_SSL_KEYFILE` and `TRONBYT_SSL_CERTFILE`.\n*   Or by fronting the service with a reverse proxy like Caddy (see `docker-compose.https.yaml`).\n*   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\"]`.\n\n**Cache:** By default, an in-memory cache is used. Redis can be configured via `REDIS_URL` for persistent caching across container restarts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftronbyt%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftronbyt%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftronbyt%2Fserver/lists"}