Skip to content

Get started

This page takes you from nothing to a camera that records around the clock and shows up live on your phone. Each step links to the page with the details; you can follow this one alone and come back for the rest.

Aperture is a network video recorder (NVR): the software that records your IP cameras. You install it on a Linux machine on your network, tell it each camera’s address, and it records everything to your own disks. You watch live video, scrub back through history and get notified about events in a web app that also works on your phone.

It is built from a few parts that run as services on that one machine:

  • nvrd, a single Go program: the web app, the API, the recorder, motion and object detection, retention and the extension supervisor, all over one SQLite database.
  • go2rtc, a stream broker. It holds the only connection to each camera and hands the picture to everything that needs it: the recorder, the detectors, every browser and Home Assistant.
  • ffmpeg, one per camera, which writes the camera’s video to disk as it arrives, without re-encoding it.

There is no Aperture cloud and no account. Footage, settings and users stay on the machine you install it on. The How it works page describes the parts in detail.

  • A 64-bit x86 Linux machine with systemd that stays on: a mini PC, an old laptop or a virtual machine. Debian 13 is what Aperture is developed on; Debian and Ubuntu are the easy path. ARM boards such as a Raspberry Pi are not supported.
  • Cameras that serve an RTSP stream. Most IP cameras do, sometimes behind a setting. Cloud-only cameras such as Ring, Nest or Blink don’t.
  • Disk space for footage. A typical camera at 4 Mbit/s fills about 43 GB a day.
  • About half an hour, most of it for the first build.

Requirements and sizing has the details: processor and memory, a storage calculator table, the ports Aperture uses and what an NVIDIA graphics card adds.

On the server, as a user who can use sudo:

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

Install Go 1.25 or newer from go.dev/dl if your distribution’s is older (go version tells you). Then get the code and install it:

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

make install builds the web app and the programs, then runs the installer with sudo. The installer refuses to continue if another program holds one of Aperture’s ports or if avahi-daemon is installed, and says which. It installs ffmpeg and Mosquitto, creates the service users and folders, downloads go2rtc and Deno at pinned versions and verifies their checksums, and enables three services without starting them.

Tell Aperture its own address in /etc/aperture/aperture.env:

# The server's address on your network (find it with: hostname -I)
APERTURE_STREAM_HOST="192.168.1.10"
# How you will open Aperture in a browser
APERTURE_PUBLIC_URL="http://192.168.1.10:8971"

Then start it:

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

The install guide explains every step, what each service does and how to uninstall.

Open http://<server-address>:8971 in a browser, for example http://192.168.1.10:8971. Where mDNS works on your network, http://aperture.local:8971 reaches it too.

A fresh install shows Welcome to Aperture and asks you to Create the administrator account: a Name, an Email and a Password of at least 8 characters, entered twice. This screen appears only once. The account you create is an administrator; anyone you add later can be limited to watching chosen cameras (see Users, roles and camera access).

  1. Open Devices in the bar on the left and choose Add camera.
  2. Give it a Camera name, such as “Front door”.
  3. Paste its address into Main stream (RTSP URL), for example rtsp://<user>:<password>@192.168.1.21:554/stream1. If the camera has a second, smaller stream, put it in Sub stream (optional, used for motion): motion detection decodes it instead of the full picture, which saves a lot of processor time.
  4. Choose Test connection. Aperture connects to the camera and shows a preview, so you know the address and the login are right before you save.
  5. Under Recording, pick a Recording mode (24/7 continuous, Motion only, Scheduled or Off) and how many days to keep in Retention (days). Seven days is the default.
  6. Choose Add camera.

The camera appears on the Dashboard within seconds. Recording starts at once; the first ten-second segment is on disk and in the timeline a few seconds later.

The stream address depends on the brand. A few common ones:

Brand Main stream Sub stream
Reolink rtsp://<user>:<password>@<ip>:554/Preview_01_main …/Preview_01_sub
TP-Link Tapo rtsp://<user>:<password>@<ip>:554/stream1 …/stream2
Hikvision rtsp://<user>:<password>@<ip>:554/Streaming/Channels/101 …/Channels/102
Dahua, Amcrest rtsp://<user>:<password>@<ip>:554/cam/realmonitor?channel=1&subtype=0 …subtype=1

Add cameras has more brands, what to switch on in the camera first, and what to do when the test fails.

The bar on the left has the four places you’ll use every day:

Dashboard Every camera live on one wall, with the weather, storage, camera capacity and the live bitrate beside it. Click a camera to open it large. See Live view.
Devices Your cameras as a table or a grid. Click one to open its panel with an overview and its settings.
Playback The recorded footage of a camera on a vertical timeline you can drag through, with events marked on it. See Playback.
Alarms Every event across your cameras, with a thumbnail, what was in it and the weather at the time. See Events and alarms.

At the bottom are Settings and, for administrators, Activity Log, Automations, Integrations and Users. Settings is grouped into your account (General, Security, Notifications), cameras (Camera Groups, Detection, Environment) and the system (Recording & Storage, System, Hardware, Extensions).

On a phone the bar moves to the bottom of the screen with Live, Playback, Alarms and Settings.

None of these are required for recording, but each is easier on the first evening than after something has happened.

  1. Set where the site is under Settings › Environment, so events and playback carry the weather, sunrise and sunset. See Site, weather, sun and moon.
  2. Point footage at a big disk or a NAS under Settings › Recording & Storage, and check the retention. See Storage.
  3. Turn on two-factor or add a passkey under Settings › Security. See Passwords, two-factor and passkeys.
  4. Put Aperture behind HTTPS if you want it on your phone as an app, with push notifications and passkeys. Phones only allow those on secure pages. See HTTPS and remote access and On your phone.
  5. Choose what should notify you under Settings › Notifications. See Notifications.
  6. Turn on object recognition under Settings › Detection if you want people, vehicles, animals and packages told apart. See Object recognition.

Nothing, unless you turn it on. Recording, live view, playback, motion detection and alerts all work without an internet connection. The optional outside calls are the weather and the place search, push notifications through your browser maker’s push service, the notification channels you set up, and the one-time download of a recognition model. What leaves your network lists every one.