Skip to content
Tilecast Docs

Installation

Tilecast Server runs on a host you control with Docker Engine and Docker Compose v2. The Compose file runs a published Stable server image and starts PostgreSQL beside it. Cloudflare Tunnel is optional.

Before you start

Section titled “Before you start”
  • Not sure which setup fits? The Setup Advisor recommends one and links the guides in order.
  • Choose a host that can stay on while displays need Tilecast. See Choose where to run Tilecast Server.
  • Choose the address that browsers and Players will use. Set this as TILECAST_PUBLIC_URL.
  • Use HTTPS before allowing access from outside a trusted local network.

Start Tilecast Server

Section titled “Start Tilecast Server”

Run these commands from the root of a clone of the Tilecast repository.

  1. Copy the example environment file.

    Repository root · Copy the environment file
    cp deploy/docker/.env.example deploy/docker/.env

  2. Edit deploy/docker/.env. Replace POSTGRES_PASSWORD with a long, random value. Do not commit this file. TILECAST_VERSION selects the installed server version: keep stable to follow Stable releases, or pin a release such as 0.11.0 for controlled upgrades.

  3. Set the address and cookie setting for your access path.

    Access path Environment values
    Trusted LAN over HTTP TILECAST_PUBLIC_URL=http://tilecast.local:8080 and TILECAST_COOKIE_SECURE=false. Restrict port 8080 to the trusted network with a firewall.
    HTTPS hostname through a reverse proxy or tunnel Set TILECAST_PUBLIC_URL=https://signage.example.org and TILECAST_COOKIE_SECURE=true.

    The Player requires HTTPS for public hostnames. It accepts HTTP for local addresses such as a private IPv4 address, localhost, or a .local name. HTTP traffic is not encrypted.

  4. Pull the server image and start the services.

    Repository root · Start Tilecast
    docker compose --env-file deploy/docker/.env -f deploy/docker/compose.yml pull
    docker compose --env-file deploy/docker/.env -f deploy/docker/compose.yml up -d

  5. Open TILECAST_PUBLIC_URL in a browser. On first visit, enter the organization name and create the first Owner account.

The server applies its database migrations before it accepts requests. There is no separate migration command.

Connect Players

Section titled “Connect Players”

The default Compose configuration disables LAN discovery. Enter the server address on each Player if it does not appear in the nearby-server list. Discovery can also fail across VLANs, guest Wi-Fi, access-point isolation, or Docker bridge networks.

When using HTTPS behind a proxy, keep TILECAST_PUBLIC_URL set to the external HTTPS address. The repository includes a reverse-proxy Compose example. The optional tunnel Compose profile starts a Cloudflare Tunnel. See Set up Tilecast with Cloudflare Tunnel for the steps, or Set up Tilecast on a local network for a LAN-only installation.

Check server readiness

Section titled “Check server readiness”

Use /healthz to check whether the server process answers. Use /readyz to check whether the database, media storage, FFmpeg, and FFprobe are ready. Replace the example address below with your configured TILECAST_PUBLIC_URL.

Check server readiness
curl --fail http://tilecast.local:8080/readyz

The Compose health check uses /readyz. A failed readiness check returns HTTP 503.

Preserve installation data

Section titled “Preserve installation data”

Compose uses two named volumes. Preserve both when replacing containers or hosts.

  • Directorypostgres_data/ Tilecast database.
    • …
  • Directorytilecast_data/ Media, backups, and cached Player releases under /data.
    • Directorymedia/ Uploaded and processed media and thumbnails.
      • …
    • Directorybackups/ Full installation archives from Settings > Backup and restore.
      • …
    • Directoryupdates/ Verified Player releases cached for deployment (including Windows after publication).
      • …

Next steps

Section titled “Next steps”