Skip to content

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.

  • /etc/aperture/aperture.env is a systemd environment file: one NAME="value" per line, # starts a comment. The aperture unit requires it; aperture-discovery reads it if present.
  • The installer creates it once from deploy/aperture.env.example and never overwrites it. After an update, compare your file with the example for new variables.
  • nvrd reads every variable once, at start. After editing the file, restart the service the variable belongs to:
Terminal window
sudo systemctl restart aperture
  • An empty value counts as unset: APERTURE_STREAM_HOST="" means “use the built-in default”.
  • The APERTURE_ONVIF_ENABLED and APERTURE_HOMEKIT_ENABLED switches must be exactly true to 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.

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.

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.

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.

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.
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.

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.

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.

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 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

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)

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.

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

Install · HTTPS and remote access · nvrctl · Troubleshooting