Configuration
Aperture keeps very little configuration in files. /etc/aperture/aperture.env holds only what must be known before the database opens: addresses, folders and paths to helper programs. Everything else (cameras, storage, retention, detection, users, integrations) is configured in the app and stored in the database. This page is the reference for the file.
How the file works
Section titled “How the file works”/etc/aperture/aperture.envis a systemd environment file: oneNAME="value"per line,#starts a comment. Theapertureunit requires it;aperture-discoveryreads it if present.- The installer creates it once from
deploy/aperture.env.exampleand never overwrites it. After an update, compare your file with the example for new variables. nvrdreads every variable once, at start. After editing the file, restart the service the variable belongs to:
sudo systemctl restart aperture- An empty value counts as unset:
APERTURE_STREAM_HOST=""means “use the built-in default”. - The
APERTURE_ONVIF_ENABLEDandAPERTURE_HOMEKIT_ENABLEDswitches must be exactlytrueto be on.
Two columns below matter: the built-in default is what the program uses when a variable is missing; the installed value is what aperture.env.example sets. The built-in defaults are meant for running from a source checkout (make run); a service install relies on the installed values.
Addresses
Section titled “Addresses”| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_HTTP_ADDR |
:8080 |
:8971 |
Where the web app and API listen. :8971 means every interface; 127.0.0.1:8971 accepts only local connections, for example when a reverse proxy on the same machine is the only way in. |
APERTURE_PUBLIC_URL |
http://localhost:8080 |
http://localhost:8971 |
How people open Aperture, for example https://nvr.example.com. Used for links in notifications, shared clip links, webhook and automation payloads, and the single sign-on callback (<url>/api/auth/oidc/callback). When it starts with https://, sign-in cookies are marked Secure. Set it before you use Aperture. |
APERTURE_STREAM_HOST |
empty | empty | The server’s LAN address (or host:port) that outside players use for the RTSP restream, for example 192.168.1.10. Without a port, the RTSP port is appended. Empty means “the host the browser used”, which is right only when you open Aperture by its IP address. Set it whenever you use a reverse proxy or a host name. |
APERTURE_TRUSTED_PROXIES |
127.0.0.0/8, ::1/128 |
commented out | The reverse proxies whose forwarding headers Aperture believes: IP addresses and CIDR ranges, comma-separated, for example 127.0.0.1, ::1, 192.168.1.5. Only from these does it take the client address from X-Forwarded-For and HTTPS from X-Forwarded-Proto; from anyone else those headers are ignored. The default trusts a proxy on the same machine only. A value replaces the default, so keep 127.0.0.1 and ::1 if a local proxy should still count; none trusts nobody. An entry that is not an address or range is skipped, with a warning in the log at start. See Client addresses. |
APERTURE_PUSH_RELAYS |
https://push.aperturenvr.com |
commented out | The push relays the phone app may register with for notifications: base URLs, comma-separated. Aperture sends notifications only to a relay on this list, so a signed-in user cannot make it post to any other address. Each notification is encrypted for the phone before it leaves; the relay sees a random device id and ciphertext. A value replaces the default; add your own relay’s URL if you run one, or set none to turn phone push off. |
APERTURE_ADVERTISE_LOCAL |
true |
commented out | Whether the phone app is told this machine’s own network addresses (the server-addresses route and the pairing QR code), so it can connect directly at home. Set false on a server only reachable at its public address, such as one in a cloud container. |
If you change the port in APERTURE_HTTP_ADDR, change it in APERTURE_PUBLIC_URL, APERTURE_URL, APERTURE_ADVERTISE_PORT and your reverse proxy too. The installer’s port check always tests 8971.
If your reverse proxy runs on another machine, add its address to APERTURE_TRUSTED_PROXIES. Until you do, every visitor appears with the proxy’s address and passkey sign-in through the proxy fails. Aperture logs ignoring forwarding headers from a peer that is not a trusted proxy with the proxy’s address the first time it ignores them.
Folders
Section titled “Folders”| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_DATA_DIR |
./data |
/var/lib/aperture/data |
Database, secrets, CLI token, extensions, exports, spool and caches |
APERTURE_RECORDINGS_DIR |
./recordings |
/var/lib/aperture/recordings |
Footage of the built-in default storage location |
APERTURE_REQUIRE_REC_MOUNT |
0 |
not set | Read by the pre-start check. 1 refuses to start when the recordings folder is not a mount point, so a disk that failed to mount does not fill the system disk. |
The service may write only below /var/lib/aperture, so both folders must stay there unless you also extend the unit’s ReadWritePaths with a drop-in. Moving them on an existing install is not a matter of changing the variables: the database stores each segment’s absolute path. See Backup and restore.
go2rtc
Section titled “go2rtc”| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_GO2RTC_URL |
http://localhost:1984 |
http://127.0.0.1:1984 |
How nvrd reaches go2rtc’s API |
APERTURE_GO2RTC_RTSP |
rtsp://localhost:8554 |
rtsp://127.0.0.1:8554 |
How nvrd and its recorders reach go2rtc’s RTSP restream. Its port is also the port advertised with APERTURE_STREAM_HOST. |
These must match what /var/lib/aperture/go2rtc.yaml listens on. Keep go2rtc’s API on 127.0.0.1: it hands out every camera’s address and password.
Integration seeds
Section titled “Integration seeds”These set a starting value. The app owns the setting from then on.
| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_MQTT_URL |
empty | tcp://127.0.0.1:1883 |
The MQTT broker address the Home Assistant integration uses until you enter one in Integrations › Home Assistant. It does not turn the integration on. |
APERTURE_ONVIF_ENABLED |
false |
commented out | Seeds the ONVIF provider switch on the very first start only. Afterwards Integrations › ONVIF & HomeKit decides. |
APERTURE_ONVIF_ADDR |
:10101 |
not set | Where the ONVIF provider listens when it is on. Read at every start. |
APERTURE_HOMEKIT_ENABLED |
false |
commented out | Seeds the HomeKit switch on the very first start only. |
Extensions
Section titled “Extensions”| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_DENO_PATH |
/usr/local/bin/deno |
/usr/lib/aperture/bin/deno |
The Deno runtime backend extensions run in |
APERTURE_EXT_SDK |
/usr/local/share/aperture-sdk/mod.ts |
/usr/lib/aperture/sdk/mod.ts |
The SDK module extensions import. Extensions may read its whole folder, so the folder must hold only this file; the pre-start check refuses anything else. |
APERTURE_URL |
http://localhost:8080 |
http://127.0.0.1:8971 |
The API address handed to backend extensions. nvrctl reads the same variable (see below). |
Aperture sets APERTURE_TOKEN, APERTURE_API and APERTURE_EXT_ID for each extension process itself. You do not set them; see Extensions.
Secrets
Section titled “Secrets”| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_JWT_SECRET |
generated | not set | Overrides the signing secret in secrets.json |
APERTURE_STREAM_SECRET |
generated | not set | Overrides the secret that signs short-lived live-stream tokens |
Leave both unset. On first start Aperture generates these, the CLI token and a 32-byte encryption key, and keeps them in data/secrets.json (mode 0600). A value set here is also written into that file. The encryption key cannot be set from the environment; it protects stored network-share, camera ONVIF and Eufy passwords, which is why secrets.json belongs in every backup.
Development
Section titled “Development”| Variable | Built-in default | Purpose |
|---|---|---|
APERTURE_WEB_DIR |
empty | Serve the web app from this folder instead of the copy built into nvrd. For frontend development only. |
Network advertisement
Section titled “Network advertisement”Read by aperture-discovery. Restart it after a change: sudo systemctl restart aperture-discovery.
| Variable | Built-in default | Installed value | Purpose |
|---|---|---|---|
APERTURE_ADVERTISE_NAME |
Aperture NVR |
Aperture NVR |
The service name shown in network browsers |
APERTURE_ADVERTISE_HOST |
aperture |
aperture |
Published as <host>.local |
APERTURE_ADVERTISE_PORT |
8971 |
8971 |
The web port in the advertisement |
APERTURE_ADVERTISE_IFACE |
automatic | commented out | Comma-separated interfaces to advertise on, for example eth0. Automatic picks every interface that is up, not loopback, has an IPv4 address and is not a Docker or VM bridge. |
nvrctl
Section titled “nvrctl”nvrctl does not read /etc/aperture/aperture.env; it reads its own environment when you run it. See nvrctl.
| Variable | Default | Purpose |
|---|---|---|
APERTURE_URL |
http://localhost:8971 |
The API address. The --url flag overrides it. |
APERTURE_DATA_DIR |
not set | Where to look for cli.token first. Without it, nvrctl looks in /var/lib/aperture/data (the installed location), then /data, ./data and ./deploy/data. |
APERTURE_SESSION_FILE |
$XDG_STATE_HOME/aperture/nvrctl-session.json |
Where the console remembers a sign-in (for 7 days) |
XDG_STATE_HOME |
~/.local/state |
Base folder for the session file |
Install scripts
Section titled “Install scripts”Read by deploy/install.sh and deploy/vendor.sh while installing. They are not part of aperture.env.
| Variable | Default | Purpose |
|---|---|---|
BIN_DIR |
<repository>/bin |
Where install.sh finds the built programs |
FFMPEG_MODE |
system |
system uses the distribution’s ffmpeg; pinned downloads a static build |
DEST |
/usr/lib/aperture/bin |
Where vendor.sh installs go2rtc and Deno |
FFMPEG_URL, FFMPEG_SHA |
a pinned build and its SHA-256 | The ffmpeg archive and checksum for pinned mode |
APERTURE_BIN |
/usr/bin/nvrd |
The binary the pre-start check verifies is still world-readable and executable (extensions need that) |
Set in the unit, not in the file
Section titled “Set in the unit, not in the file”The aperture unit sets PATH so that /usr/lib/aperture/bin comes first: a pinned ffmpeg there wins over the distribution’s. Resource limits (CPUQuota, MemoryHigh, MemoryMax, TasksMax) are also set in the unit; change them with sudo systemctl edit aperture, as Requirements shows. Edits to /etc/systemd/system/aperture.service itself are lost on the next install; drop-ins are kept.
Configured in the app
Section titled “Configured in the app”Everything else lives in the database and changes without a restart:
| What | Where |
|---|---|
| Cameras, streams, recording mode, retention | Devices |
| Storage allocation, destinations, network shares | Settings › Recording & Storage |
| Motion and object recognition | Settings › Detection and each camera’s editor |
| Site, location, timezone, units | Settings › Environment |
| Home Assistant, ONVIF, HomeKit, webhooks, API tokens, single sign-on | Integrations |
| Users and their cameras | Users |
| Notification channels and rules | Settings › Notifications |
| Backups and diagnostics | Settings › System |
Related
Section titled “Related”Install · HTTPS and remote access · nvrctl · Troubleshooting