Upgrading

An upgrade replaces the binary or the container image. The data directory stays. When the new version starts, it applies the database migrations it needs.

How migrations work

• Migrations run automatically at start, before the server serves requests. There is no separate migrate command.
• The core has one migration track. Each format that stores data (Debian today) has its own track. The server applies the core track first, then each format in order.
• The server records the applied version of each track in the schema_migrations table.
• The server refuses to start on a database that is newer than the binary. This means you cannot go back to an older version after a newer one has migrated the database. To roll back, restore a backup from before the upgrade.

Caution

Take a backup before every upgrade. See Backups and data. It is the only way to go back.

Upgrade the container

Each release pushes the image to ghcr.io/telesphorepo/telesphorepo. To stay on one release line, use an X.Y tag in place of latest.

1. Back up the data volume.

2. Pull the new image:

   docker pull ghcr.io/telesphorepo/telesphorepo:latest

3. Stop and remove the old container. The volume stays:

   docker stop telesphorepo
   docker rm telesphorepo

4. Start a new container on the same volume:

   docker run -d --name telesphorepo -p 8080:8080 -v telesphorepo-data:/data ghcr.io/telesphorepo/telesphorepo:latest

5. Check the log and the health route:

   docker logs telesphorepo
   curl http://localhost:8080/healthz

   /healthz answers ok when the database answers.

Use the same -v volume and the same TR_* environment variables as before. If you keep the master key in TR_MASTER_KEY, pass it again.

Upgrade the binary

Download the new archive from GitHub Releases and check it against SHA256SUMS.

1. Back up the data directory.

2. Stop the old process.

3. Replace the binary.

4. Start the new binary with the same TR_DATA_DIR.

You can check the version with telesphorepo version.

What carries over

• Settings. They live in the database, so they stay. Changes you made in the UI apply to the new version.
• Storage. The blobs stay where they are. A new version does not move them.
• Running work. A restart during a storage move or a Nexus sync is safe. The move or the sync continues from its last saved position when the new version starts.
• Sessions. UI sessions are rows in the database, so people stay signed in.

Gotchas

• Downtime. The server is down between the stop and the start. A publish that is in flight fails and the client must retry. Plan the upgrade for a quiet time.
• Unknown variables. The server logs a warning for a TR_* variable that matches no setting. After an upgrade, read the log to see if a name changed.
• Read the migration step. If the log shows a migration error, do not start the old version on the same data. Restore your backup, then ask for help with the error text.