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

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.
Read the release notes of each version after yours.
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. After the license term ends, a license with a version cap covers only versions up to the cap. See expiry.
For disaster recovery, stop the Core and copy its data folder to a safe place. See 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

If the Core runs as a service, update it:

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:

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

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:

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.

Download and run the new installer:

Download Synnax Core 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.

Download the new binary:

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:

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.

Pull the new image. Use a version tag, such as synnaxlabs/synnax:0.59.0, so you can go back to the old image:
```
docker pull synnaxlabs/synnax:<version>
```
Remove the old container. The data and the certificates stay in their volumes:
```
docker stop synnax && docker rm synnax
```

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:

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:

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:

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.

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

Stop the Core.
Undo the update with the new binary:
```
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.
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:

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.

Activate a license

Next in TLS

Set up TLS