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.
One-command install
Section titled “One-command install”On a Debian 12 or 13, or Ubuntu 22.04, 24.04 or 26.04 machine (x86-64, with systemd), run:
curl -fsSL https://aperturenvr.com/install | sudo shThe 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.
-
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-daemonis 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 whataptwould remove and asks before it removes anything. -
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, andAPERTURE_TRUSTED_PROXIESwhen 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_HOSTto this machine’s address on your network. - This machine’s address,
-
Storage. Where footage goes. The default is
/var/lib/aperture/recordings. If you choose another disk, setup createsaperture-recordingson it and mounts that folder at/var/lib/aperture/recordingswith 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. -
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.
-
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. -
Install. It installs
ca-certificates,ffmpegandmosquittowithapt, 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. -
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.
The NVIDIA driver
Section titled “The NVIDIA driver”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.
After the install
Section titled “After the install”| 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.
Install from source
Section titled “Install from source”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.
1. Prepare the server
Section titled “1. Prepare the server”Work as a normal user that can use sudo. Install the basic tools and Node.js:
sudo apt updatesudo apt install -y git make curl unzip nodejs npmnode --versionnode --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:
sudo rm -rf /usr/local/gosudo tar -C /usr/local -xzf go1.25.*.linux-amd64.tar.gzecho 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile && . ~/.profilego versionRemove avahi
Section titled “Remove avahi”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:
dpkg -s avahi-daemon 2>/dev/null | grep StatusIf that prints Status: install ok installed, remove it:
sudo apt remove avahi-daemonFree the ports
Section titled “Free the ports”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:
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.
2. Get the code and install
Section titled “2. Get the code and install”git clone https://github.com/TheOriUHD/aperture.gitcd aperturemake installRun 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.
What make install does
Section titled “What make install does”- Builds the web app (
npm ci && npm run buildinweb/) and copies it into the Go source, so the programs carry the interface inside them. It then checks that the copied bundle has anindex.htmland is not older than any file inweb/src, and stops if not. - Builds four static programs into
bin/:nvrd(the daemon),nvrctl(the admin console),apdiscovery(network advertisement) andapdetect(the object-recognition worker). - Runs
deploy/install.shas root, which:- checks the machine: root, systemd,
x86_64, no avahi, free ports, all four programs built; - installs
ca-certificates,mosquitto,ffmpeg, andcurlandunzipfor the downloads below, withaptif they are missing; - creates two system users with
systemd-sysusers:aperture-go2rtc, which runs the video broker, andaperture-ext(uid 65533), the base identity for sandboxed extensions; - creates the folders under
/var/lib/aperturewithsystemd-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.envfromdeploy/aperture.env.exampleif 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.
- checks the machine: root, systemd,
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.
Installed files
Section titled “Installed files”| 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) |
Installer options
Section titled “Installer options”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. |
3. Tell Aperture its address
Section titled “3. Tell Aperture its address”Open the configuration file:
sudo nano /etc/aperture/aperture.envSet 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.
4. Start it
Section titled “4. Start it”sudo systemctl start mosquitto aperture-go2rtc aperture aperture-discoverysystemctl status aperture --no-pagerYou should see active (running). If not, read the log with journalctl -u aperture -n 50 --no-pager and see Troubleshooting.
The three services
Section titled “The three services”| 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.
5. Open it
Section titled “5. Open it”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.
Where data and footage live
Section titled “Where data and footage live”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 |
A bigger disk for footage
Section titled “A bigger disk for footage”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:
sudo blkid /dev/sdb1echo 'UUID=<uuid from blkid> /var/lib/aperture/recordings ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstabsudo systemctl daemon-reloadsudo mount /var/lib/aperture/recordingsTo 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=1For 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.
Never nest recordings inside data
Section titled “Never nest recordings inside data”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.
Uninstall
Section titled “Uninstall”cd ~/aperturesudo deploy/uninstall.shThis 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-extandaperture-go2rtcusers, because files on disk still belong to them, - the
mosquittoandffmpegpackages.
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.
Docker
Section titled “Docker”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.