Skip to content

Install

This page takes you from a fresh Debian or Ubuntu server to a running Aperture, in about ten minutes. There are two ways: the one-command install downloads a release and sets everything up with a wizard; installing from source builds the web app and the programs on the server itself with make install. Both install the same systemd services. Check Requirements first.

On a Debian 12 or 13, or Ubuntu 22.04, 24.04 or 26.04 machine (x86-64, with systemd), run:

Terminal window
curl -fsSL https://aperturenvr.com/install | sudo sh

The script downloads aperture-setup, checks its SHA-256 against the checksum written into the script, installs it as /usr/local/bin/aperture-setup and starts it. You can read the script first: open the same address in a terminal with curl -fsSL https://aperturenvr.com/install.

aperture-setup is a full-screen wizard. It looks at the machine, asks a few questions, shows every step and every file before it does anything, and changes nothing until you press Enter on its Review screen. It works in a terminal of 80 × 24 characters or larger.

  1. Machine. It checks the system, memory and processor, the free space where footage will go, the ports Aperture needs (8971, 1883, 1984, 8554 and 8555, naming the program that holds one), whether avahi-daemon is installed, an NVIDIA card and its driver, and whether Aperture is already installed. A blocking problem is explained under its row. For avahi, press a: setup shows what apt would remove and asks before it removes anything.

  2. Access. How you will open Aperture:

    • This machine’s address, http://<address>:8971. Nothing else to set up. Phones can watch, but installing the app on a phone, push notifications and passkeys need HTTPS.
    • A domain name with HTTPS. Setup installs Caddy from your distribution’s packages (the choice is off where apt has none) and configures it for the name. The name must point at this machine and ports 80 and 443 must reach it.
    • Behind my own reverse proxy. Setup sets Aperture’s side (APERTURE_PUBLIC_URL, and APERTURE_TRUSTED_PROXIES when the proxy runs in Docker or on another machine) and shows the settings for Caddy, nginx, Traefik, Nginx Proxy Manager or Cloudflare Tunnel. It saves them in /etc/aperture/proxy/. See HTTPS and remote access.
    • Only on my Tailscale network. Setup runs tailscale serve, which gives Aperture an HTTPS address on your tailnet. Tailscale must be installed and connected, with HTTPS certificates enabled for the tailnet.

    In every case setup sets APERTURE_STREAM_HOST to this machine’s address on your network.

  3. Storage. Where footage goes. The default is /var/lib/aperture/recordings. If you choose another disk, setup creates aperture-recordings on it and mounts that folder at /var/lib/aperture/recordings with a systemd mount unit, because the service may only write below /var/lib/aperture. Aperture then does not start without that disk instead of filling the system disk. Each choice shows about how many days of footage fit at 4 Mbit/s per camera. Network storage (SMB, SFTP) is added later in the app.

  4. Options. Object recognition (off, on the processor, or on an NVIDIA GPU), installing the NVIDIA driver (see below), Home Assistant’s MQTT broker, HomeKit, and the version to install.

  5. Review. Setup downloads the release archive into /var/cache/aperture-setup, checks its SHA-256, and lists every step with its exact commands and every file it will write, in full: the units, aperture-harden, the SDK, /etc/aperture/aperture.env, and programs by size and checksum. Nothing else has changed at this point.

  6. Install. It installs ca-certificates, ffmpeg and mosquitto with apt, creates the users and folders, downloads the pinned go2rtc and Deno and checks their SHA-256, runs the same ffmpeg check as the manual install, installs the programs, writes the configuration, starts the services and waits until Aperture answers. If a step fails, the screen shows the error and the last lines of its output; r tries again.

  7. Finish. It opens Aperture’s address the way a browser does: the health check, the web app’s page and the live-video path, and the certificate for an HTTPS address. Each problem it finds comes with what to change. Then it creates your administrator account (name, email, password) and shows the address, with a QR code for your phone (v).

On a machine where Aperture is installed, the wizard offers to update it or to change its settings. Both keep cameras, footage, accounts and settings.

When setup finds an NVIDIA card without a driver, Options offers to install it. Its help line names exactly what goes on the machine. The commands are the ones Settings › Detection shows in the app: the kernel headers, NVIDIA’s package repository, the driver with the open kernel modules, and the built-in nouveau driver turned off. They run last, while Aperture already records. The driver loads after a restart; the last screen offers it (r) and asks before it restarts the machine.

Setup leaves the driver to you, and says why, when Secure Boot is on (the kernel module must be signed with a key you enrol at the console), for cards older than the RTX 20 series, on distributions other than those above, and when NVIDIA packages from the distribution itself are installed. Object recognition covers those cases.

Command What it does
sudo aperture-setup The wizard again: update, or change how Aperture is reached, where footage goes and the options.
sudo aperture-setup update Installs the newest release. It keeps a copy of the programs it replaces and restarts Aperture once. If the new version does not come up (it keeps exiting, or does not answer within two minutes), setup puts the copy back and restarts it again by itself.
sudo aperture-setup doctor Checks the services, the version, the footage disk, the GPU, and the address the way a browser does, and says what to change.
sudo aperture-setup status The services, the version, the address and the free space for footage.
aperture-setup plan … Prints the steps and files for the answers given as flags, and changes nothing.
sudo aperture-setup install --yes … Installs without the wizard, from the same flags. aperture-setup --help lists them.
sudo aperture-setup uninstall Removes the services and programs. It keeps /etc/aperture and /var/lib/aperture unless you add --purge-config or --purge-state.

To pass a command through the one-liner, add it after sh -s --, for example curl -fsSL https://aperturenvr.com/install | sudo sh -s -- doctor.

Releases come from https://get.aperturenvr.com. Setup installs a release only when its manifest carries a valid Aperture signature, so a tampered download host cannot hand it other files. APERTURE_RELEASE_BASE points setup at another host; for a release you built and signed yourself (make release RELEASE_KEY=FILE), APERTURE_RELEASE_KEY names your public key. And --archive FILE --sha256 HEX installs from an archive you downloaded.

This builds Aperture from the repository on the server itself and installs it with deploy/install.sh. Use it to run a version that has no release, or on a machine the wizard does not support.

Work as a normal user that can use sudo. Install the basic tools and Node.js:

Terminal window
sudo apt update
sudo apt install -y git make curl unzip nodejs npm
node --version

node --version must print v18 or newer; the web app’s build tools (Vite 5) need it. If your distribution ships an older Node.js, install a current one from nodejs.org first.

Install Go 1.25 or newer (the version go.mod asks for). Distribution packages are often older, so use the official build: download the linux-amd64 tarball from go.dev/dl into your home folder, then unpack it:

Terminal window
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.*.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile && . ~/.profile
go version

The installer stops if the avahi-daemon package is installed, even when the service is disabled or masked. Avahi holds UDP port 5353 exclusively, and Aperture needs that port for its aperture.local advertisement and for HomeKit pairing. Check for it:

Terminal window
dpkg -s avahi-daemon 2>/dev/null | grep Status

If that prints Status: install ok installed, remove it:

Terminal window
sudo apt remove avahi-daemon

Aperture’s services need ports 8971 (web app), 1883 (MQTT), 1984, 8554 and 8555 (video). The installer checks each one and stops, naming the program, if something other than an Aperture component holds it. You can check yourself:

Terminal window
sudo ss -lntup | grep -E ':(8971|1883|1984|8554|8555)\b'

No output means the ports are free. Requirements lists every port and what it is for.

Terminal window
git clone https://github.com/TheOriUHD/aperture.git
cd aperture
make install

Run make install as your normal user, not with sudo: it builds as you and asks for your sudo password only for the install step. It needs internet access for the npm packages, the Go modules and the pinned downloads below.

  1. Builds the web app (npm ci && npm run build in web/) and copies it into the Go source, so the programs carry the interface inside them. It then checks that the copied bundle has an index.html and is not older than any file in web/src, and stops if not.
  2. Builds four static programs into bin/: nvrd (the daemon), nvrctl (the admin console), apdiscovery (network advertisement) and apdetect (the object-recognition worker).
  3. Runs deploy/install.sh as root, which:
    • checks the machine: root, systemd, x86_64, no avahi, free ports, all four programs built;
    • installs ca-certificates, mosquitto, ffmpeg, and curl and unzip for the downloads below, with apt if they are missing;
    • creates two system users with systemd-sysusers: aperture-go2rtc, which runs the video broker, and aperture-ext (uid 65533), the base identity for sandboxed extensions;
    • creates the folders under /var/lib/aperture with systemd-tmpfiles;
    • downloads the pinned runtime and verifies each file’s SHA-256 before installing it: go2rtc 1.9.14 (the video broker) and Deno 2.9.5 (the extension runtime). A checksum mismatch stops the install;
    • checks that ffmpeg and ffprobe work for recording: it encodes a two-second test clip to MPEG-TS and probes its duration, and stops if that fails;
    • installs the programs, the extension SDK and the pre-start check script;
    • creates /etc/aperture/aperture.env from deploy/aperture.env.example if it does not exist yet, and a credential-free /var/lib/aperture/go2rtc.yaml;
    • installs and enables the three systemd units, so they start on boot. It does not start them.

The installer is safe to run again: it replaces programs, units and the SDK, and leaves /etc/aperture/aperture.env and everything under /var/lib/aperture alone.

Path What it is
/usr/bin/nvrd, /usr/bin/nvrctl The daemon and the admin console
/usr/lib/aperture/bin/ go2rtc, deno, apdiscovery, apdetect
/usr/lib/aperture/sdk/mod.ts The extension SDK (alone in its folder on purpose: extensions may read that whole folder)
/usr/libexec/aperture/aperture-harden Pre-start checks, run before every start of nvrd
/etc/systemd/system/aperture*.service The three units
/usr/lib/sysusers.d/aperture.conf, /usr/lib/tmpfiles.d/aperture.conf Users and folder layout
/etc/aperture/aperture.env Your configuration
/var/lib/aperture/ Database, secrets, footage and downloads (see below)

make install runs deploy/install.sh without options. You can run the script yourself after make build-native:

Option Effect
--start Start the services at the end and check that aperture.service is running
--skip-vendor Do not download go2rtc and Deno again (they must already be installed)
--system-ffmpeg Use the distribution’s ffmpeg (the default)
--pin-ffmpeg Download a pinned static ffmpeg instead. Not recommended: the distribution package is the tested path and gets security updates, and the installer refuses a build that fails its smoke test.

Open the configuration file:

Terminal window
sudo nano /etc/aperture/aperture.env

Set these two lines. Other devices use them to reach Aperture:

# The server's LAN address (find it with: hostname -I)
APERTURE_STREAM_HOST="192.168.1.10"
# How people open Aperture in a browser. Plain http on your LAN is fine to start with.
APERTURE_PUBLIC_URL="http://192.168.1.10:8971"

APERTURE_STREAM_HOST goes into the RTSP addresses Aperture hands to Home Assistant and other players. APERTURE_PUBLIC_URL goes into links in notifications, shared clips and single sign-on. Leave the other lines as they are; Configuration explains every variable.

Terminal window
sudo systemctl start mosquitto aperture-go2rtc aperture aperture-discovery
systemctl status aperture --no-pager

You should see active (running). If not, read the log with journalctl -u aperture -n 50 --no-pager and see Troubleshooting.

Unit Runs As Notes
aperture-go2rtc go2rtc, the video broker. It connects to the cameras once and shares each stream with recording, motion detection and viewers. aperture-go2rtc Config in /var/lib/aperture/go2rtc.yaml, which go2rtc rewrites itself and which holds camera passwords (mode 0600). API on 127.0.0.1:1984, RTSP on 8554, WebRTC on 8555. Memory capped at 1 GB.
aperture nvrd: the web app and API, recording (ffmpeg), motion and audio detection, retention, object recognition, integrations and extensions. root Reads /etc/aperture/aperture.env. Runs aperture-harden before each start. Sandboxed by systemd: it can write only below /var/lib/aperture, cannot see /home, and is capped at six cores and 5 GB (Service limits).
aperture-discovery apdiscovery, which advertises the server on the LAN over mDNS as aperture.local. a throwaway user (DynamicUser) Stateless; if it stops, nothing else notices.

All three restart by themselves if they exit (Restart=always), and systemd never gives up restarting them. nvrd runs as root because it starts each backend extension under its own unprivileged user id; the systemd sandbox limits what it can touch.

When you stop or restart aperture, nvrd shuts down in order: extensions first, then the recorders, each closing the segment it is writing, then the web server. That normally takes a second or two; systemd allows 45 seconds.

Go to http://<server address>:8971, for example http://192.168.1.10:8971. On networks where mDNS works, http://aperture.local:8971 also reaches it.

On a fresh install Aperture shows Welcome to Aperture and asks you to create the administrator account: a name, an email address and a password of at least 8 characters. This screen appears only while no account exists.

Then add your first camera. Getting started walks through the first setup.

Everything Aperture stores lives under /var/lib/aperture:

Path Contents
data/aperture.db (with -wal and -shm) The SQLite database: cameras, users, settings, events, the index of every recorded segment
data/secrets.json Generated secrets, including the key that encrypts stored network-share and camera ONVIF passwords. Back it up with the database.
data/cli.token The local admin token nvrctl uses
data/ext/ Installed extensions, each owned by its own user id
data/exports/ Finished exports, removed after 24 hours unless a working share link keeps them
data/spool/ Footage waiting to be uploaded to a network destination
data/frame-cache/, data/rcache/ Scrub thumbnails and footage fetched back from network shares
data/homekit/ HomeKit pairing data
recordings/<camera id>/ Footage in 10-second .ts segments named by their start time, plus events/ with event thumbnails
ai/ Object-recognition runtimes and models, downloaded when you turn recognition on
go2rtc.yaml go2rtc’s configuration

The service may only write below /var/lib/aperture. To record onto a separate disk, mount it at /var/lib/aperture/recordings before you start Aperture for the first time. For example, with an ext4 disk:

Terminal window
sudo blkid /dev/sdb1
echo 'UUID=<uuid from blkid> /var/lib/aperture/recordings ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount /var/lib/aperture/recordings

To make Aperture refuse to start when that disk is missing, instead of quietly recording onto the system disk, add this line to /etc/aperture/aperture.env:

APERTURE_REQUIRE_REC_MOUNT=1

For a second local disk, mount it below /var/lib/aperture (for example /var/lib/aperture/disk2) and add it as a local destination in the app. For a NAS, add an SMB or SFTP destination in Settings › Recording & Storage instead of mounting the share. See Storage.

aperture-harden refuses to start nvrd when APERTURE_RECORDINGS_DIR is inside APERTURE_DATA_DIR. Keep them as siblings, as the installer sets them: /var/lib/aperture/data and /var/lib/aperture/recordings. The object-recognition downloads live beside the data folder (/var/lib/aperture/ai) for the same reason.

The same pre-start script also refuses to start when the database exists but secrets.json is missing (starting would generate a new key and make stored share passwords unreadable), and it re-applies owner-only permissions to the database, secrets and token files on every start.

Terminal window
cd ~/aperture
sudo deploy/uninstall.sh

This stops and disables the three services and removes the units, the programs, the downloaded runtime, the SDK and the sysusers and tmpfiles entries. It keeps:

  • /etc/aperture (your configuration),
  • /var/lib/aperture (the database, the encryption key and all footage),
  • the aperture-ext and aperture-go2rtc users, because files on disk still belong to them,
  • the mosquitto and ffmpeg packages.

To delete more, add options:

Option Effect
--purge-config Also delete /etc/aperture
--purge-state Also delete /var/lib/aperture. Asks you to type DESTROY first.
--yes, -y Skip that confirmation

make uninstall runs sudo deploy/uninstall.sh without options.

The repository still contains a Docker Compose setup in deploy/. It is the older way of running Aperture and is being retired; these docs cover the systemd install.

Requirements · Configuration · Getting started · Updates