Enterprise

# Upgrade the Core

> Move a Synnax Core to a newer version, then update the Console and standalone Drivers.

Upgrade a Synnax Core to get new features and fixes. When the Console finds a Core on a different minor version, it shows the two versions in place of the workspace.

## Before you upgrade

1. Check the version of your Core with `synnax --version`. You can upgrade in one step from v0.47.0 or later to the current release. Upgrades from v0.46 or earlier are not supported.
2. Read the [release notes](https://docs.synnaxlabs.com/releases) of each version after yours.
3. Check that your license covers the new version. Core 0.60 and later accept only signed license keys from the portal, so get one before you upgrade from 0.59. See [numeric license keys](https://docs.synnaxlabs.com/reference/enterprise/license#numeric-license-keys). After the license term ends, a license with a version cap covers only versions up to the cap. See [expiry](https://docs.synnaxlabs.com/reference/enterprise/license#expiry).
4. For disaster recovery, stop the Core and copy its data folder to a safe place. See [Back up the Core](https://docs.synnaxlabs.com/reference/enterprise/production-checklist#back-up-the-core).

The new Core changes the data folder when it first starts, and an older Core cannot always read it after that. Before the first start of a new version, the Core backs up its metadata to the `backups` folder in the data folder: channels, ranges, users, and the other records it stores. It keeps the three newest backups. A backup holds no telemetry, so only a copy of the data folder keeps all data. If the backup fails, the Core does not start.

## Upgrade

**Linux**

If the Core runs as a [service](https://docs.synnaxlabs.com/reference/enterprise/service), update it:

```bash
sudo synnax update 0.60.1
```

The command downloads the new Core and checks its signature. It stops the service, puts the new binary in place of the old one, and starts the service. It then waits up to 10 minutes for the new Core to commit the update. To change the wait, add `--timeout`, such as `--timeout 30m`. If the new Core fails, the command puts the old Core back and starts it. The old binary stays next to the new one, with an `.old` extension. If the wait ends first, the command fails and leaves the new Core to finish. If that Core then undoes the update, run `synnax update undo` to put the old Core back.

An older Core cannot download an update, so the command fails. Then download the new binary and update with it:

```bash
curl -LO https://github.com/synnaxlabs/synnax/releases/download/core/v0.60.1/synnax-v0.60.1-linux
```

```bash
chmod +x ./synnax-v0.60.1-linux && sudo ./synnax-v0.60.1-linux update --file ./synnax-v0.60.1-linux
```

If the Core runs in a terminal, download the new binary as above. Stop the Core with **Ctrl+C**, then put the new binary in place of the old one:

```bash
chmod +x ./synnax-v0.60.1-linux && sudo mv ./synnax-v0.60.1-linux "$(command -v synnax)"
```

Start the Core with the same flags and from the same folder as before, so it uses the same data folder.

**Windows**

Download and run the new installer:

[Download Synnax Core](https://github.com/synnaxlabs/synnax/releases/download/core/v0.60.1/synnax-setup-v0.60.1.exe) v0.60.1 for Windows

The installer updates a Core service in the same way as `synnax update`. It waits for the new Core to commit the update. If the new Core fails, the installer starts the old Core again and stops with an error. The service keeps its settings in `C:\ProgramData\Synnax\config.yaml`, which the installer does not change. If you clear **Install Synnax as a Windows Service**, the installer removes the service.

**macOS**

Download the new binary:

```bash
curl -LO https://github.com/synnaxlabs/synnax/releases/download/core/v0.60.1/synnax-v0.60.1-macos
```

Stop the Core with **Ctrl+C**, then put the new binary in place of the old one:

```bash
chmod +x ./synnax-v0.60.1-macos && sudo mv ./synnax-v0.60.1-macos "$(command -v synnax)"
```

Start the Core with the same flags and from the same folder as before, so it uses the same data folder.

**Docker**

1. Pull the new image. Use a version tag, such as `synnaxlabs/synnax:0.59.0`, so you can go back to the old image:

   ```bash
   docker pull synnaxlabs/synnax:<version>
   ```

2. Remove the old container. The data and the certificates stay in their volumes:

   ```bash
   docker stop synnax && docker rm synnax
   ```

3. Start a new container with the same options, volumes, and flags as the old one. The license is bound to the `--mac-address`, so keep the same address. Keep the certificate volume, or `--auto-cert` makes a new CA that your clients do not trust:

   ```bash
   docker run -d --name synnax --mac-address 02:5a:00:00:00:01 \
     -p 9090:9090 -v synnax-data:/synnax/synnax-data \
     -v synnax-certs:/usr/local/synnax/certs \
     synnaxlabs/synnax:<version> <the same flags as before>
   ```

If the new Core fails, it puts the data back and stops. Start a container with the old image again.

On its first start, the new Core logs `running migrations` and one `migration completed` line for each change to stored data. Wait for `Synnax is running and available at <address>`.

To check the version, run `synnax --version`.

## When an update fails

The new Core commits the update after it opens the data and before it serves clients, so no client writes to the data before the commit. If the new Core fails before the commit, it puts the backup back and stops with a message such as:

```plaintext
Update to Core 0.61.0 failed: no space left on device. The data is back at Core 0.60.1.
Run Core 0.60.1, or fix the cause and run `synnax update retry`.
```

The update also fails when the license covered the old version but does not cover the new one. When you stop the Core before the commit, it puts the backup back, and its next start updates the data again. When the Core stops before the commit without a chance to clean up, for example after a power loss, its next start undoes the update.

After a failed update, the new version does not start on the data, so a service or a container that restarts does not repeat the update. `synnax update` and the Windows installer start the old Core again. In other cases, run the old version. To try the new version again, fix the cause, then run:

```bash
synnax update retry
```

For a Core that does not run as a service, add `--data <data folder>`.

If you snapshot the data folder before each update, you can turn off the backup with the `--no-update-backup` start flag. The Core then does not undo a failed update.

## Update the Console and Drivers

* **Console app** -> the Console gets the matching release from its Core and shows **Update available**. Click it to update. The update needs no internet access. The Core serves updates for macOS and Windows. On Linux, install the new release by hand.
* **Console in a browser** -> updates with the Core.
* **Standalone Drivers** -> install the new release on each computer. See [Install a standalone Driver](https://docs.synnaxlabs.com/reference/enterprise/driver/install).

The desktop Console does not open the workspace when its major or minor version differs from the Core. Click **Update Console** to install the Console that matches the Core, or **Open in browser** to use the Console that the Core serves. A browser reloads the page by itself to get the Console that matches the Core. The client libraries warn and still connect. Upgrade the Core first, then the Console and Drivers. A Console older than 0.60 shows errors instead of the activation screen when a Core 0.60 has no license, so upgrade the Console with the Core.

A user with permission to update the Synnax version, such as an Owner, also sees the newest stable Console when its minor version is newer than the Core’s. The Console asks you to confirm first, because it cannot open the workspace until you upgrade the Core. When a newer Core release exists, this user also gets a notification with the command that updates the Core.

Drivers after 0.60 number the EtherCAT modules on IgH from 1, as on the built-in master. If a Driver uses IgH, delete its [EtherCAT devices](https://docs.synnaxlabs.com/reference/hardware/ethercat/configure-device) after you upgrade it from 0.60 or earlier, and before you start a task. The next scan finds the modules again, and you configure them again. Until then, tasks on that network do not start.

> Synnax Desktop has its own Core, which updates with the app and backs up its metadata in the same way.

## Go back to an earlier version

Synnax does not support a downgrade. A Core does not open data that a newer Core opened, and stops with a message such as `Data was last opened by Core 0.61.0. Run Core 0.61.0 or newer, or undo the update with synnax update undo.` To go back, undo the update:

1. Stop the Core.

2. Undo the update with the new binary:

   ```bash
   synnax update undo
   ```

   For a Core service, the command uses the data folder of the service. On Linux, run it with `sudo`. Otherwise, add the same `--data` flag as `synnax start`.

   The command restores the backup of the last update and prints the Core version to run. If `synnax update` installed the new binary, the undo also puts the old binary back. If the Core already undid the update, the undo only puts the old binary back. With no old binary to put back, it refuses.

3. If the undo did not put the old binary back, install that version of the Core. Then start the Core.

To restore a backup again, or to go back further, list the backups with `synnax update history`, then run `synnax update undo <backup>`. Each backup is named `<time>-<version>`, where `<version>` is the Core that last ran on the data before the backup.

The undo puts back the metadata of the backup. Telemetry stays, including telemetry recorded after the update. The undo moves the telemetry of channels created after the update to an `orphaned-<time>` folder in the `backups` folder. Telemetry deleted after the update does not come back. The undo cannot run while a Core runs on the data folder. If an undo stops before it finishes, the Core does not start until you run the undo again.

In Docker, run the undo with the image of the new version, such as `0.61.0`:

```bash
docker run --rm -v synnax-data:/synnax/synnax-data --entrypoint /synnax/synnax \
  synnaxlabs/synnax:0.61.0 update undo
```

To go back to the exact state before the upgrade, replace the data folder with the copy you made before the upgrade instead, then start the earlier version.