Running it · Chapter 13

Behind a proxy.

Nexview speaks plain HTTP inside. If you want to reach it from outside, put a proxy with https in front of it, or use a VPN into your network, which is the safer choice. With its own address, such as https://nexview.example.com, Nexview needs no configuration at all. This chapter shows the three things worth doing: a sub-path, a proxy Nexview believes, and the right public address.

Account first, then open it up

Create the account from the setup wizard from your own network. Only afterwards do you forward a port, because as long as there is no account, anyone who can open the page can go through the wizard. Whoever hangs Nexview openly on the network before the first sign-in has a problem regardless of everything else.

Under a sub-path

Instead of a subdomain of its own, Nexview can run under a path of a shared domain, such as https://example.com/nexview/. For that you add one variable to the environment block of the Compose file and restart the container:

NEXVIEW_URL_BASE: /nexview

Any path works, /tools/nexview too. If the variable is empty, everything behaves as before. With the path set, Nexview answers every address twice, with and without the prefix. That is needed because proxies are set up in two ways: some pass the path through unchanged (the recommended setup), others strip it before forwarding. Also the Docker health check and the webhooks of Radarr and Sonarr call the server directly at the root. The value is tidied when it is read: a leading slash is added, a trailing one removed. /api is forbidden as a prefix, it would collide with the interface itself.

Ready-made examples for the four common proxies:

location /nexview {
    proxy_pass http://127.0.0.1:5173;
    proxy_set_header Host $host;
}

handle /nexview* {
    reverse_proxy 127.0.0.1:5173
}

handle_path, which strips the path, works just as well.

- traefik.http.routers.nexview.rule=PathPrefix(`/nexview`)
- traefik.http.services.nexview.loadbalancer.server.port=8000

A stripprefix middleware works just as well. With Nginx Proxy Manager you add a “Custom Location” /nexview on the proxy host and forward it to the host and port Nexview listens on. Nothing more is needed, no advanced configuration.

Trusting the proxy

Behind a proxy that ends TLS the request reaches Nexview as http. Every address Nexview builds from it would be an http address, such as the redirect address for signing in through a provider. And all requests look as if they came from the same address, that of the proxy. Two settings take care of this, one for the scheme and the address, one for the cookie.

NEXVIEW_CLIENT_IP

This is the setting for trusted proxies. It tells Nexview how to find the address of whoever is asking, and whether it may believe the scheme in X-Forwarded-Proto. The header is read only when a proxy is named here. Without the setting Nexview ignores it, because it can be faked just like X-Forwarded-For.

The proxy has to pass on X-Forwarded-For and X-Forwarded-Proto. Nginx Proxy Manager, Caddy and Traefik do that by themselves. With the setting, Nexview takes the rightmost value, the one your nearest proxy added, and only http or https. With proxy:2 that is the scheme the request had when it reached that proxy, not necessarily the browser’s.

NEXVIEW_COOKIE_SECURE

Your sign-in is kept in an HttpOnly cookie. The browser sends it back on its own, and no script on the page can read it. Whether it also carries the Secure attribute, meaning it travels only over https, is decided by this variable.

With NEXVIEW_CLIENT_IP=proxy, auto follows the proxy’s scheme, and the cookie becomes Secure as soon as the value is https. If an outer proxy ends https and passes plain http inwards, set NEXVIEW_COOKIE_SECURE=on. The same goes for the short-lived cookie of a sign-in through a provider, which bridges the ten minutes you spend at the provider.

Two details for the curious. The server in the image reads X-Forwarded-Proto out of the box from senders on the machine itself, such as a proxy next to it on the host network. And the variable concerns the scheme, never the host, which comes from the Host header as the proxy passes it on.

The public address

Under “Settings › System › Address” is the address your people type into the browser. Invitations, mails, providers and links use it, and the redirect address for signing in is built from it. If it changes later, Nexview asks first when a provider still knows the old one. The “Address as seen by Radarr/Sonarr” is on the same page. It is needed only when the public address does not work for the return channel, inside a Docker network for instance, or when a sign-in guard or a self-signed certificate sits in front.

The page’s content rules

Nexview tells your browser where it may load things from and where it may send things to. Everything else it refuses. The most important result: no script on the page can send data to an address other than Nexview’s own. You normally need not change any of it. For three cases there are switches:

About the posters: Nexview does not build calendar posters itself, it passes on the address Radarr or Sonarr stored, and that depends on your metadata provider. The usual ones (TMDB, TheTVDB, fanart.tv) are allowed already. If yours is something else, the posters do not appear, and the browser says so only in its console. NEXVIEW_IMG_SOURCES=https://images.example.org fixes it.

What else https brings

Web push works only over https. On iPhone and iPad, Nexview also has to be on the Home Screen. Both are in the chapter Notifications.

Next come backups and updates: Backups and updates. All environment variables at a glance are on the Self-host page.