Update Tilecast Server

A Tilecast Server update can include database migrations, Studio changes, server code, and deployment changes. Back up the installation before changing versions.

Server release channels

Tilecast Server has three release channels:

Stable is the recommended channel for normal installations. Stable releases are published as versioned images such as ghcr.io/gbyo/tilecast-server:0.26.0, with stable and latest as aliases for the newest Stable release.
Beta lets you test the next Stable release. Beta images are versioned like ghcr.io/gbyo/tilecast-server:0.26.0-beta.1, and beta names the newest release of either kind. When Stable catches up, beta moves to it.
Development tracks main through the development image tag and may be unstable. Use it only for development and testing.

See Releases and downloads for how versions are ordered.

TILECAST_VERSION in deploy/docker/.env is the one place that selects the installed server version. Keep stable to follow Stable releases, use beta to test early, or pin an explicit release for controlled upgrades.

Before you update

Read the release notes for the version you plan to install.
Create and verify a Tilecast backup. A database migration can make the upgraded database unreadable to the older version, so the backup is the recovery path.
Save your deployment configuration and external secrets separately.
Record the server version and commit that is currently running. Studio shows them under Settings → Operations as the version, channel, and commit.

A full recovery needs PostgreSQL data and Tilecast media from the same point in time.

Update a Stable installation

If this installation still uses the former Compose file that builds the server from source (its server service has a build: section), update the deployment files first. The simplest path is to pull them in the existing checkout:

git pull --ff-only

This one-time transition is the last update that touches the Git checkout. Confirm deploy/docker/compose.yml now selects a published image through TILECAST_VERSION and has no build: section under server before continuing.

Set TILECAST_VERSION in deploy/docker/.env to the release you want to install, for example 0.26.0.
Pull the new image and recreate the services without deleting their volumes.
Repository root · Update 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
```
After the one-time transition above, a production update never needs git pull, git checkout, or --build.
Wait for Tilecast Server to finish startup and any database migrations, then check readiness.
Check server readiness
```
curl --fail https://signage.example.org/readyz
```
Open Studio and check the fleet, Activity, media library, and at least one Player before considering the update finished.

Do not use docker compose down --volumes during an update. That removes the named data volumes.

Reload Studio after the update to load its current entry document. Tilecast keeps versioned assets cached and returns a missing-file response for assets from an older build. See the deployment contract.

If the new version does not become ready

Read the server log before making more changes:

docker compose --env-file deploy/docker/.env -f deploy/docker/compose.yml logs server

A database migration can make an older Tilecast version unable to use the upgraded database. Changing TILECAST_VERSION back and starting the older image against that database is not always a safe rollback.

Unless the release notes specifically say an application-only rollback is supported, restore the verified pre-update backup so the database and media return to the same point in time.

Development installs

To deliberately track main instead of Stable releases, set TILECAST_VERSION=development and pull:

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

Stable and Beta builds report their version and channel there too. Development builds report a -dev version and the development channel in Settings → Operations, so they are never mistaken for a release. To build and run the server from a source checkout instead, add the development Compose override:

docker compose --env-file deploy/docker/.env -f deploy/docker/compose.yml -f deploy/docker/compose.dev.yml up -d --build

Player versions are separate

Updating Tilecast Server does not update Android, Windows, or Edge Players, even though they ship in the same release.

Use Player updates for Player releases and follow any server/Player update order listed in the release notes.