Skip to content
Tilecast Docs

Developers

Tilecast is an AGPL-3.0-only project in the gbyo/tilecast repository. The repository contains the server, Studio, Android and Linux Players, shared packages, deployment files, and this documentation site.

Repository layout

Section titled “Repository layout”
  • Directorytilecast/
    • Directoryapps/ Product applications.
      • Directoryserver/ Go server, HTTP API, and database migrations.
        • …
      • Directorydashboard/ React and TypeScript management app, Tilecast Studio.
        • …
      • Directoryplayer-android/ Kotlin and Jetpack Compose Player for Android TV devices.
        • …
      • Directoryplayer-linux/ Electron Player for Linux kiosk devices.
        • …
      • Directoryedge/ Tilecast Edge, the new Linux player: a Rust daemon, a WPE WebKit renderer, update and migration helpers, and a small user-session bridge.
        • …
      • Directorydocs/ Astro and Starlight public documentation site.
        • …
    • Directorypackages/ Shared design tokens and application contracts.
      • …
    • Directorydeploy/ Docker deployment and optional network integrations.
      • …
    • Directorydocs/ Engineering references, API descriptions, and implementation contracts.
      • …

Run the server and Studio locally

Section titled “Run the server and Studio locally”

You need Go (use the version in apps/server/go.mod), Node.js with npm, and a PostgreSQL database. From the repository root:

  1. Install workspace and Go dependencies:

    Repository root · Install dependencies
    make bootstrap

  2. Set TILECAST_DATABASE_URL to a development database Tilecast can use:

    Set the development database
    export TILECAST_DATABASE_URL='postgres://localhost:5432/tilecast?sslmode=disable'

  3. Start the Go server in one terminal:

    Terminal 1 · Start the server
    make dev-server

  4. Start the Vite development server in a second terminal:

    Terminal 2 · Start Studio
    make dev-dashboard

To explore Studio with sample data instead of an empty database, run a demo installation.

The Go server applies pending migrations during startup. Complete the one-time Owner setup in Studio when using a new database. Vite reloads dashboard changes; restart the Go server after changing server code. Server settings are read from TILECAST_* environment variables; deploy/docker/.env.example lists the deployment settings.

Check and build changes

Section titled “Check and build changes”

From the repository root, make check runs the repository’s documented format, lint, test, and static checks. make build builds the dashboard bundle, server binary, and Android debug APK. Security reports follow the private process in the repository’s Security Policy.

Read the contribution guide

Work on Tilecast Edge

Section titled “Work on Tilecast Edge”

Tilecast Edge lives in apps/edge. Its software milestones M1 to M10 are merged, physical hardware qualification (M11) is next, and no signed release is published yet. Read apps/edge/README.md and apps/edge/AGENTS.md first. From apps/edge:

Terminal window
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

The renderer and the session bridge are C projects built with CMake on Linux. The session bridge needs GLib, json-glib, GStreamer, and WirePlumber 0.5 development packages. Hardware tests never touch a real TV or monitor: test daemons use empty device directories, the HDMI-CEC test in CI uses the kernel’s vivid virtual driver, and the session bridge test uses a real PipeWire with a virtual microphone. The hardware capability matrix says what each feature needs and how it is tested.

Work on the public docs

Section titled “Work on the public docs”

The docs site is an npm workspace. Run these commands from the repository root:

Repository root · Docs commands
npm run docs:dev
npm run docs:check
npm run docs:build

Follow the documentation style guide. The docs build also checks internal links.

Technical references

Section titled “Technical references”