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.
        • …
      • 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:

    Terminal window
    make bootstrap

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

    Terminal window
    export TILECAST_DATABASE_URL='postgres://localhost:5432/tilecast?sslmode=disable'

  3. Start the Go server in one terminal:

    Terminal window
    make dev-server

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

    Terminal window
    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 the public docs

Section titled “Work on the public docs”

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

Terminal window
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”