# Upgrading

> Move to a new Telesphorepo version. Replace the binary or image, and migrations run on start.

Source: https://docs.telesphorepo.com/operations/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](/operations/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:

   ```sh
   docker pull ghcr.io/telesphorepo/telesphorepo:latest
   ```

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

   ```sh
   docker stop telesphorepo
   docker rm telesphorepo
   ```

4. Start a new container on the same volume:

   ```sh
   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:

   ```sh
   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](https://github.com/Telesphorepo/Telesphorepo/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](/operations/moving-storage/) or a [Nexus sync](/operations/nexus-migration/) 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.