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.

Before you update

Read the release notes for the version you plan to install.
Create and verify a Tilecast backup.
Save your deployment configuration and external secrets separately.
Record the Git tag or commit that is currently running.

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

Update a source-based Compose installation

From the repository clone, fetch the version you want to install.
Repository clone · Fetch releases
```
git fetch --tags origin
```
Check out the release tag or reviewed commit. Do not update a production server from an unreviewed working tree.
Repository clone · Check out the release
```
git checkout <release-tag>
```
Rebuild and recreate the services without deleting their volumes.
Repository root · Rebuild Tilecast
```
docker compose --env-file deploy/docker/.env -f deploy/docker/compose.yml up -d --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.

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. Checking out the previous source code and starting it 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.

Player versions are separate

Updating Tilecast Server does not update Android, stable Linux, or Edge Players.

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