Updating OpticWatch

Install a new release, or change edition, without losing data.

OpticWatch never updates itself or checks for new versions on its own: you update when you choose to. From 1.2.0, one command does it on Linux; on other computers, and from 1.1.1 or earlier, you update by hand. Your data lives in Docker, not in the release folder, so either way nothing is lost.

Which version you are running

Open Settings and find License: it shows the edition and version, for example “Pro 1.2.0”. The VERSION file in the OpticWatch folder says the same.

Update with one command (1.2.0 and later)

Starting with OpticWatch 1.2.0, supported Linux installations include an update manager, opticwatch-update.sh. It finds the newest release of your edition, downloads it, checks that it is a genuine OpticWatch release, backs up your installation, installs the new release next to the current one and checks that it works. You do not download an archive yourself. It downloads and verifies the new release first, then asks before it changes anything in your installation. It runs only when you run it; OpticWatch still never updates on its own.

Before you start

Linux on a 64-bit Intel or AMD (x86-64) computer. On Windows, macOS and ARM computers, update by hand.
OpticWatch 1.2.0 or later, running, from the folder you will update. Updating from 1.1.1 or earlier is done by hand, once.
Docker Engine with the Docker Compose plugin 2.20 or newer (check with docker compose version).
bash 4.3 or newer, curl, GNU tar and coreutils, gzip, sha256sum and flock, which standard Linux servers already have.
A user that can run docker, usually a member of the docker group. The update manager does not need root (run it with sudo only if your user cannot run docker), and does not change Docker's settings.
Internet access from the server to opticwatch.dev (Free) or cloud.opticwatch.dev (Pro and Integrator).
Free disk space in the folder that holds your OpticWatch folder: at least 1 GB plus four times the size of the new release.

Update

Go to the folder of the release that is running
The folder you start OpticWatch from, for example opticwatch-free-v1.2.0. Its name ends in the version you run:
Terminal
```
cd ~/opticwatch-free-v1.2.0
```
Download the newest update manager
Terminal
```
curl -fsSLO https://opticwatch.dev/downloads/opticwatch-update.sh
```
This replaces the copy that came with your release, if there is one, with the newest. Every release from 1.2.0 includes it, so you can also skip this step and use the copy already in the folder.
Check the file you downloaded
Terminal
```
sha256sum opticwatch-update.sh
```
A copy downloaded in the previous step must print exactly this checksum, which is that of the newest release's copy:
Output
```
11650ce64ea518ad956d7be93c6e5989f678569b29546c2371688624da0a5ef5
```
If it prints anything else, delete the file and do not run it. (A copy that came with an older release has its own, different checksum; skip this step for it.) See How you know an update is genuine.
See what is available
Terminal
```
bash opticwatch-update.sh --check
```
This changes nothing in OpticWatch (it only creates the opticwatch-updates folder it works in). It shows your version and either available: OpticWatch Free 1.3.0 (released …) or that your installation is up to date.
Update
Terminal
```
bash opticwatch-update.sh
```
It downloads and verifies the new release, shows the version it will install and the folders it will use, then asks Continue? [y/N]. Type y. It then backs up, unpacks and builds the new release while the old one keeps running, and switches. OpticWatch is unavailable for a short while during the switch.
Check the result
When it has finished it says, for example:
Output
```
OpticWatch Free is now 1.3.0, running from /home/you/opticwatch-free-v1.3.0.
The previous release folder was kept: /home/you/opticwatch-free-v1.2.0 (remove it once you are happy).
Backup taken before the update: /home/you/opticwatch-backups/opticwatch-backup-free-….tar
```
Open OpticWatch and check the version under Settings, License. If the interface still looks like the old version, reload the page once (Ctrl+Shift+R). From now on, the new folder is your OpticWatch folder: run docker compose commands, backups and the next update from there.

What it checks, in order

That this is Linux with the tools it needs, that the folder it runs in is the running OpticWatch (1.2.0 or later), and that no other update is running.
Which release is newest for your edition. A paid installation asks the licensing service, authenticating as itself from inside a container.
The download, twice, before anything is unpacked: its signature, edition, version, size and SHA-256.
A new backup, which it then verifies belongs to this installation and holds its encryption key.
The new release's images, built while the old release runs, and checked to contain the release's own program and interface.
After the switch: both services healthy, the interface reachable, the new version running, the same installation, and the database fully upgraded.

Options and results

--check: Report whether an update exists. Changes nothing in OpticWatch.
--yes: Also -y. Do not ask for confirmation, for running it from a script. Without it, and without a terminal, it refuses to update.
--help: Show how to use it.

Its exit status says how it ended:

0: Updated, or already up to date.
1: Not updated. The running installation is unchanged, or was switched back to it.
2: An option it does not know, or --help.
3: Stopped after the database was upgraded. Needs you; see below.
4: Switching back did not complete. Needs you; see below.

Free, Pro and Integrator

Free needs no license key. Updates come from this website. A Free installation only ever installs Free releases; the update manager never downloads a paid build.
Pro and Integrator must already be activated online. The update manager authenticates with the installation's existing activation, from inside a container: you do not enter your license key again or paste a download link from an email. The activation credential stays inside that container; the update manager never sees it and never shows it, and the short-lived download link is never printed.
An update never changes edition: Pro installs Pro releases and Integrator installs Integrator releases. To change edition, follow Changing edition.
A paid installation that is not activated online, or uses an offline license certificate, cannot authenticate. The update manager says so and changes nothing; update by hand.
Only newer, stable releases (such as 1.3.0) are offered, never test builds or older versions.

Your data during an update

Before it changes anything, the update manager takes a complete backup with docker compose run --rm backup and verifies it: the file is complete, PostgreSQL can read it, and it belongs to this installation with its encryption key. Verifying is not the same as restoring it: keep your own copies off the server too, as Back up and restore describes.

Everything carries over to the new release:

Your cameras, sites, monitoring history, incidents, settings, license and activation, in the database volume, which the new release uses as it is.
The encryption key and database password, in the secrets volume.
Your .env and any Compose override file (docker-compose.override.yml or compose.override.yml, or their .yaml forms), copied into the new folder. Changes made to docker-compose.yml itself are not carried over; put them in an override file. Files an override mounts must be outside the release folder, with absolute paths: the update manager refuses to start until they are.

The new release is unpacked beside the old one, which is kept. The update manager never deletes a release folder, a backup, a download or a Docker volume. Next to your release folders you will find:

Text

opticwatch-free-v1.2.0/    the release you ran before, kept
opticwatch-free-v1.3.0/    the new release
opticwatch-backups/        every backup, shared by all release folders
opticwatch-updates/        downloads, and a receipt for every update

In every release the update manager installs, backups points to the shared opticwatch-backups folder. Backups already in the old folder's backups are linked into it as well, not moved, so removing an old release folder never removes a backup.

If an update does not succeed

Before the switch: If the download, a verification, the backup or the build fails, the running installation has not been touched. It says what failed. Fix it and run the update manager again: it reuses a download it has verified and a release it has prepared, and takes a fresh backup. After a failed verification it tells you to remove the download first.
The new release does not start, and the database was not changed: It switches back to the previous release by itself, checks that it is healthy, and says “running again, exactly as before”. The new release's folder is kept so you can read its logs.
The database was already upgraded: It stops OpticWatch and explains what to do, with the exact commands. It does not start the previous release, which cannot run on the upgraded database, does not restore the backup, and deletes nothing.

In the last case you can find the cause with docker compose logs api in the new folder and start the new release again once it is fixed, or go back to the previous release by restoring the backup taken just before the update, with the commands it printed.

Interrupting the update manager (Ctrl+C) before the switch leaves the running installation as it was. During the switch it first restores a consistent state, then stops. There is no separate rollback command: going back after a successful update is restoring a backup.

Every update leaves a receipt in opticwatch-updates/receipts/: the versions and folders, the backup it took and how it ended. It holds no password, key or license.

Updating from 1.1.1 or earlier

1.1.1 and earlier do not include the update manager, and it cannot update them: run there, it says your installed version does not support automatic updates and changes nothing. Update to 1.2.0 once by hand, below. From then on, use the update manager.

How you know an update is genuine

Every release is signed with OpticWatch's release-signing key, and your installation has the matching public keys built in. It refuses a release whose signature, edition, version, size or checksum does not match before unpacking anything, whatever website or link it came from.

The update manager itself is a script you run, so check it first. The checksum above is that of the copy inside the signed release 1.2.0. Because it is shown on the same website the script comes from, it proves the file arrived complete and unchanged, but not that the website itself can be trusted. If you would rather not download a script at all, run the copy that came in your release folder (bash opticwatch-update.sh there): it installs the same releases with the same checks.

Getting a new release

Free: from the Free download page.
Pro and Integrator: request a download link on the download page with your purchase email and license key.

Update by hand

Back up, in the current OpticWatch folder
Terminal or PowerShell
```
docker compose run --rm backup
```
Always do this first. See Back up and restore.
Extract the new release next to the old one
Go up one folder and extract the new archive there, then move into the folder it creates. Replace the example names with your new release's file and folder names:
Terminal or PowerShell
```
cd ..
tar -xzf NEW-RELEASE.tar.gz
cd NEW-RELEASE-FOLDER
```
Start the new release
Terminal or PowerShell
```
docker compose up -d --build
```
--build makes sure Docker packages the new release instead of reusing the previous one.
Check it
Terminal or PowerShell
```
docker compose ps
```
Wait for postgres, api and web to show (healthy). Then check the version under Settings, License. If the interface still looks like the old version, reload the page once (Ctrl+Shift+R, or Command-Shift-R on a Mac); your browser may have kept the old one.

Nothing needs to be copied from the old folder, unless you created a .env file there for an advanced setting such as a different port; copy that file into the new folder before starting. Database changes are applied automatically when the new release starts, all at once: they either complete or change nothing. Keep the old folder until you are happy with the new release.

Changing edition

Moving from Free to Pro, or between Pro and Integrator, is the same procedure with the other edition's download. All editions share one database, so nothing is converted or lost in either direction. After moving to a paid edition, activate your license.

Going back to an older release

Downgrades are not supported. An older release refuses to start on a database a newer one has updated, and says so in its log, rather than risk damaging it. To go back, restore the backup you made before updating, using the older release.