HTTPS and remote access
Aperture speaks plain HTTP on port 8971 and has no built-in HTTPS. This page shows how to put a reverse proxy in front of it for HTTPS, which headers and timeouts the proxy needs, and how to reach Aperture from outside your network without exposing more than you mean to.
Why HTTPS
Section titled “Why HTTPS”Browsers allow some features only on a secure (HTTPS) page. http://192.168.1.10:8971 is not one, so over plain HTTP:
- you cannot install Aperture as an app on a phone or desktop,
- push notifications that arrive while the app is closed cannot be switched on (the browser hides the service worker and push APIs),
- passkeys do not work. They also need a host name: a passkey cannot be bound to an IP address.
Everything else works over plain HTTP on your LAN. HTTPS also keeps your password and session cookie off the wire when you use Aperture on a network you do not control.
Choose how to reach it from outside
Section titled “Choose how to reach it from outside”| Option | What is exposed | Notes |
|---|---|---|
| VPN (WireGuard, Tailscale or your router’s VPN) | Nothing; you join your home network | The safest option. Live video connects over WebRTC as it does at home. Combine it with a proxy that only answers on the LAN and VPN if you want HTTPS features. |
| Reverse proxy on the internet | Port 443 of the proxy | Needed if devices must reach Aperture without a VPN. Turn on two-factor authentication for every account. |
| Reverse proxy on the LAN only | Nothing outside | HTTPS features at home. A certificate obtained with a DNS challenge does not need the server to be reachable from the internet. |
Caddy obtains and renews certificates by itself and forwards WebSocket connections, long-lived event streams and large uploads without extra settings. With Caddy on the same machine as Aperture:
nvr.example.com { reverse_proxy 127.0.0.1:8971}Caddy passes the original Host header and sets X-Forwarded-For and X-Forwarded-Proto by default, which is what Aperture needs. A proxy on the same machine is trusted out of the box.
If Caddy runs on another machine, use the server’s address instead, reverse_proxy 192.168.1.10:8971, and add Caddy’s address to APERTURE_TRUSTED_PROXIES (see Client addresses).
nginx needs more settings: the WebSocket upgrade, the original Host, no buffering, longer timeouts and a larger upload limit.
map $http_upgrade $connection_upgrade { default upgrade; '' close;}
server { listen 443 ssl; http2 on; # nginx before 1.25.1: write "listen 443 ssl http2;" instead server_name nvr.example.com;
ssl_certificate /etc/letsencrypt/live/nvr.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/nvr.example.com/privkey.pem;
# Custom object-recognition models can be up to 2 GB; backups and extension bundles are smaller. client_max_body_size 2g;
location / { proxy_pass http://127.0.0.1:8971; proxy_http_version 1.1;
# Keep the name the browser used: sign-in, passkeys and the CSRF check depend on it. proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme;
# The client's address. Aperture believes it only from a trusted proxy. proxy_set_header X-Forwarded-For $remote_addr;
# Live video runs over a WebSocket. proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;
# Event streams and live video must not be buffered or cut off. proxy_buffering off; proxy_request_buffering off; proxy_read_timeout 1h; proxy_send_timeout 1h; }}If the proxy listens on a port other than 443, use proxy_set_header Host $http_host; so the port stays in the header; $host drops it.
What the proxy must do
Section titled “What the proxy must do”The examples above cover these points. If you use another proxy (Traefik, HAProxy, a NAS’s built-in proxy), check each one.
| Requirement | Why |
|---|---|
| Forward WebSocket upgrades | Live video goes through /api/v1/cameras/<id>/ws, a WebSocket that carries the WebRTC set-up and the MSE fallback stream. |
Keep the original Host header |
The passkey relying party is the host name the browser sees. Changes (saving settings, adding cameras) are refused with “cross-origin request blocked” when the browser’s Origin does not match Host. |
Send X-Forwarded-Proto: https |
Aperture uses it to build the passkey origin. It counts only from a trusted proxy. |
Set X-Forwarded-For, and be a trusted proxy |
A proxy on the same machine is trusted by default; one on another machine must be listed in APERTURE_TRUSTED_PROXIES. See Client addresses. |
| Do not buffer responses | The change feed and notification streams are server-sent events. Aperture sends X-Accel-Buffering: no and a keepalive comment every 25 seconds, so any idle timeout above 30 seconds works; buffering delays every event. |
| Allow large uploads | A configuration restore can be up to 256 MB, an extension bundle 50 MB, a custom detection model 2 GB. nginx’s default limit is 1 MB. |
| Prefer HTTP/2 | Over HTTP/1.1 a browser opens at most six connections per site, and each open event stream holds one. HTTP/2 shares one connection. |
Set Aperture’s addresses
Section titled “Set Aperture’s addresses”After the proxy works, tell Aperture its public address in /etc/aperture/aperture.env:
APERTURE_PUBLIC_URL="https://nvr.example.com"APERTURE_STREAM_HOST="192.168.1.10"# Only if the proxy runs on another machine, here 192.168.1.5:APERTURE_TRUSTED_PROXIES="127.0.0.1, ::1, 192.168.1.5"Then restart it:
sudo systemctl restart aperture| Variable | Set it to | Used for |
|---|---|---|
APERTURE_PUBLIC_URL |
The HTTPS address people open | Links in notifications and shared clips, webhook and automation links, the single sign-on callback (https://nvr.example.com/api/auth/oidc/callback), and whether sign-in cookies are marked Secure |
APERTURE_STREAM_HOST |
The server’s LAN address | The RTSP restream addresses (rtsp://192.168.1.10:8554/…) Aperture hands to Home Assistant, VLC and other recorders. The proxy forwards only the web app, not RTSP, so this must not be the proxy’s name. |
APERTURE_TRUSTED_PROXIES |
The proxy’s address, if it is not on the same machine | Which connections may tell Aperture the client’s address and that the browser used HTTPS. Default 127.0.0.0/8, ::1/128. See Client addresses. |
Passkeys are bound to the host name they were created on. A passkey made at nvr.example.com does not work at another name or at the IP address.
Live video through the proxy
Section titled “Live video through the proxy”Aperture’s player tries WebRTC first and falls back to MSE over the WebSocket:
- WebRTC carries the video directly between the browser and go2rtc on port 8555. On the LAN or over a VPN this connects at once.
- From the internet, port 8555 is usually not reachable, so WebRTC does not connect. After five seconds the player switches to MSE, which streams through the WebSocket and therefore through the proxy.
So remote live view works through the proxy alone, but each camera takes about five seconds longer to appear than at home. A VPN avoids the wait.
Client addresses
Section titled “Client addresses”The client’s address appears in the activity log and on each signed-in device in Settings › Security, and it keys the rate limit for requests that are not signed in (30 at once, then 10 per second). Behind a proxy, every connection comes from the proxy, so the real address has to come from a header the proxy adds. Any client can send such a header too, so Aperture believes it only from a proxy you trust (internal/clientip):
APERTURE_TRUSTED_PROXIESlists the trusted proxies as IP addresses and CIDR ranges, comma-separated. The default,127.0.0.0/8, ::1/128, trusts a proxy on the same machine and nothing else.- When the connection comes from a trusted proxy, Aperture reads
X-Forwarded-Forfrom the right and takes the first address that is not itself a trusted proxy. Whatever a client wrote further left is ignored, so a proxy that appends toX-Forwarded-Foris as safe as one that overwrites it. WithoutX-Forwarded-Forit usesX-Real-IP.X-Forwarded-Proto: httpsmarks the request as HTTPS, which the passkey origin depends on. - From any other sender, Aperture ignores and removes
X-Forwarded-For,X-Real-IP,X-Forwarded-Proto,X-Forwarded-Host,True-Client-IPandForwarded, and uses the address of the connection.True-Client-IPis never read.
If the proxy runs on another machine, add its address in /etc/aperture/aperture.env and restart Aperture:
APERTURE_TRUSTED_PROXIES="127.0.0.1, ::1, 192.168.1.5"A value replaces the default, so keep 127.0.0.1 and ::1 if a proxy on the same machine should still count. none trusts nobody.
Until the proxy is listed, every visitor appears with the proxy’s address, all of them share one rate-limit bucket, and passkey sign-in through the proxy fails. The first time Aperture ignores a peer’s headers it logs ignoring forwarding headers from a peer that is not a trusted proxy with that peer’s address.
A client that reaches port 8971 directly can no longer choose the address it is logged under, but it still talks plain HTTP. If the proxy runs on the same machine and nothing else needs the LAN port, you can bind Aperture to localhost with APERTURE_HTTP_ADDR="127.0.0.1:8971". Then http://192.168.1.10:8971 and aperture.local stop working, and every client, including scripts using the API, must go through the proxy.
What not to expose
Section titled “What not to expose”Forward only port 443 of your proxy, or nothing at all if you use a VPN. Never forward these to the internet:
| Port | Why |
|---|---|
| 8971 | Aperture’s own HTTP port. Plain HTTP, with no certificate. Put the proxy in front instead. |
| 1984 | go2rtc’s API. It hands out every camera’s address with its password. Aperture binds it to 127.0.0.1; keep it there. |
| 8554 | The RTSP restream. It has no password of its own. |
| 8555 | go2rtc’s WebRTC port. Not needed from outside when the MSE fallback is used. |
| 1883 | The MQTT broker. Home Assistant traffic, controls such as arming and record mode. |
| 10101, 3702 | The ONVIF provider and its discovery. It answers without a login when it is on. |
| HomeKit, 5353 | Local-network protocols. |
Your cameras should not be reachable from the internet either. Aperture is the only thing that needs to talk to them.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause |
|---|---|
| Pages load, but saving anything fails with “cross-origin request blocked” | The proxy rewrites Host (nginx’s default is the upstream address). Set proxy_set_header Host $host;. |
| Tiles show “No signal” through the proxy, fine at home | The WebSocket upgrade is not forwarded. Add the Upgrade and Connection headers. |
| Live view through the proxy takes about five seconds per camera | Usually expected: WebRTC cannot connect from outside, and the player falls back to MSE. Use a VPN for instant start. |
| Sign-in does not stick on the LAN address | APERTURE_PUBLIC_URL is HTTPS; use the HTTPS address. |
| The activity log and devices list show the proxy’s address for everyone, or passkeys fail only through the proxy | The proxy runs on another machine and is not in APERTURE_TRUSTED_PROXIES. The log names it: ignoring forwarding headers from a peer that is not a trusted proxy. Add its address and restart. |
| Restore, model or extension upload fails with 413 | The proxy’s body-size limit. Raise client_max_body_size. |
| Home Assistant or VLC gets an RTSP address with the proxy’s name | APERTURE_STREAM_HOST is empty. Set it to the server’s LAN address and restart. |
| Single sign-on fails after the redirect | APERTURE_PUBLIC_URL does not match the address registered with the identity provider. See Single sign-on. |