Skip to content

Updates

Aperture updates the same way it installs: pull the new source, run make install, restart. Your configuration in /etc/aperture and everything in /var/lib/aperture are left alone. This page covers the update itself, what changes in the database, how to read the version number and how to go back.

  1. Read the release notes. CHANGELOG.md lists what changed in each version.
  2. Make a rollback point. An update can change the database schema, and those changes only go forward. A copy of the database and secrets.json lets you go back exactly; Backup and restore shows how. Downloading a configuration backup under Settings › System is quicker but covers less.
  3. Check internet access. The build downloads npm packages and Go modules, and the installer downloads go2rtc and Deno again.

From the folder you cloned into:

Terminal window
cd ~/aperture
git pull
make install
sudo systemctl restart aperture-go2rtc aperture aperture-discovery

make install rebuilds the web app and the four programs, then runs the installer, which replaces the programs, the units and the SDK, re-downloads and verifies the pinned go2rtc and Deno, and reloads systemd. It does not restart anything; the last line does.

During the restart, nvrd closes the segment each recorder is writing before it exits, so the gap in footage is a few seconds. Live view reconnects by itself.

After the update:

  • Compare /etc/aperture/aperture.env with deploy/aperture.env.example for new variables. The installer never edits your file.
  • Check the version (below) and the log: journalctl -u aperture -n 50 --no-pager.

Releases are git tags named v<version>, for example v1.2.0:

Terminal window
cd ~/aperture
git fetch --tags
git tag --list 'v*'
git checkout v1.2.0
make install
sudo systemctl restart aperture-go2rtc aperture aperture-discovery

git checkout of a tag leaves the clone on that version. To follow the main branch again, run git checkout main before your next git pull.

The database schema is versioned by numbered migrations embedded in nvrd (internal/store/migrations). When nvrd starts, it opens the database and applies every migration newer than the highest one recorded in the schema_migrations table, in order, before the web server starts listening.

  • Automatic. There is nothing to run by hand.
  • One transaction each. A migration either applies completely or not at all. If one fails, nvrd logs open store: apply <file>: … and exits, systemd starts it again, and it fails again: the web app stays down until you roll back the program or fix the cause. Earlier migrations of the same update stay applied.
  • Forward only. There are no down migrations. An older nvrd does not undo a newer schema; it starts on it without a warning.
  • Usually quick. Most migrations add a column or a table. A large one can delay the start; the web app answers once it is done.

The version is built in from git when you run make install:

Build from Version reads
Exactly a release tag 1.2.0
Four commits after that tag 1.2.0-4-g1a2b3c4 (the commit count since the tag and the commit)
A checkout with uncommitted changes or untracked files +local appended, for example 1.2.0+local
Source without git tags 0.0.0-dev

The short commit is stored next to it. Where to see them:

  • In the app: Settings › General, under About, the Version row shows 1.2.0 (1a2b3c4).
  • From the server, without signing in: curl -s http://127.0.0.1:8971/api/v1/system/version.
  • In the log: every start logs starting nvrd with the version (journalctl -u aperture | grep 'starting nvrd').
  • nvrctl --version shows the version nvrctl was built with, which matches nvrd when both came from the same make install.

Because migrations only go forward, an older version runs against a database the newer one may have changed. Most migrations only add columns and tables, which an older version ignores, but that is not guaranteed for every release. The safe way back restores the database copy you made before the update.

  1. Stop Aperture:

    Terminal window
    sudo systemctl stop aperture-discovery aperture aperture-go2rtc
  2. Check out and install the version you were on:

    Terminal window
    cd ~/aperture
    git checkout v1.1.0
    make install
  3. Restore the database and secrets.json you saved before the update, as Backup and restore describes. Delete any aperture.db-wal and aperture.db-shm from the newer database first.

  4. Start it:

    Terminal window
    sudo systemctl start mosquitto aperture-go2rtc aperture aperture-discovery
  5. Footage recorded since your copy is on disk but not in the restored index. Click Re-scan under Settings › Recording & Storage to index it. Events from that time are not recovered.

Without a database copy, you can still try step 2 alone. If the older version starts and works, keep it; if it fails on the newer schema, go forward again to the newer version.

A configuration backup made by the newer version cannot be restored into the older one: restore refuses a backup with a higher schema.

Install · Backup and restore · Troubleshooting · Development