--- id: built-in-tls title: Built-in HTTPS and HTTP authentication modes sidebar_label: Built-in HTTPS description: Configure direct HTTPS, local certificates, or direct HTTP authentication. --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Built-in HTTPS and HTTP authentication modes SeerrNG can terminate HTTPS itself. This is useful for a direct LAN deployment where adding Caddy, Traefik, Nginx, or another reverse proxy would be unnecessary. It also supports direct HTTP authentication for trusted local installations that cannot use TLS. The default listener remains HTTP on `PORT`, and direct HTTP authentication is enabled with a warning when built-in TLS is disabled. HTTPS is still the recommended choice for authenticated sessions: | Mode | Listener | Browser session behavior | Use when | | --- | --- | --- | --- | | `disabled` | HTTP on `PORT` (5055 by default) | Cookies follow the request transport, including non-Secure cookies on HTTP; a warning is shown | A reverse proxy terminates HTTPS, or a trusted LAN cannot use TLS | | `disabled` + `SEERR_ALLOW_HTTP_AUTH=false` | HTTP on `PORT` | Session cookies are HTTPS-only; direct HTTP login does not persist | Direct browser access must require HTTPS | | `self-signed` | HTTPS on the configured HTTPS port; HTTP either redirects or returns an HTTPS upgrade response | HTTPS-only cookies | A direct LAN deployment needs encryption without an external proxy | | `provided` | HTTPS on the configured HTTPS port; HTTP either redirects or returns an HTTPS upgrade response | HTTPS-only cookies | The operator already has a certificate and private key | `SEERR_ALLOW_HTTP_AUTH=true` and any enabled TLS mode are mutually exclusive. SeerrNG refuses to start if both are configured, so a deployment cannot silently choose an insecure session path while the operator expects TLS. Set `SEERR_ALLOW_HTTP_AUTH=false` when TLS is disabled but direct HTTP sign-in must remain unavailable. ## First-run and administrator settings On a fresh installation, the setup page offers the same transport choices before the first media-server login: 1. **Self-signed HTTPS** is the recommended direct-installation choice. 2. **Provided certificate** is for a certificate and private key mounted into the SeerrNG process. 3. **HTTP authentication** is enabled by default when HTTPS is disabled, after the setup page's risk acknowledgement is accepted. Saving a first-run choice writes it to the persistent settings file. Restart SeerrNG before attempting the first login. This is intentional: changing the listener and session-cookie policy while the process is serving requests would make the result ambiguous. The setup page keeps media-server choices disabled until the active transport can persist a browser session. If a previous version of the page saved the media-server details before the session was established, restart SeerrNG after fixing the transport choice and use the normal `/login` page to sign in again. Do not submit the first-run Jellyfin hostname a second time; it is already stored and the setup page will guide you back to sign-in. Existing installations with built-in TLS disabled are migrated so direct HTTP authentication works by default. Set `SEERR_ALLOW_HTTP_AUTH=false` if the installation must remain HTTPS-only, or use **Settings > Network > Browser Transport Security** to select a mode, save it, and restart SeerrNG. When enabling HTTPS, leave **Redirect HTTP to HTTPS** off for the first restart, verify the HTTPS URL and certificate trust, then enable the redirect and restart again. With the redirect disabled, the HTTP port does not serve the authenticated application; it returns an HTTPS upgrade response. The same settings page can disable HTTPS again. If a certificate mistake makes the UI unreachable, use the startup recovery override `SEERR_TLS_MODE=disabled` and restart. Direct HTTP authentication is then available by default; set `SEERR_ALLOW_HTTP_AUTH=false` if the recovery path must remain HTTPS-only. Listener changes are restart-required. The status endpoint and the Network page show the active mode, the saved mode, environment overrides, and whether a restart is pending. The HTTP redirect is intentionally a separate setting so an administrator can verify HTTPS before making HTTP redirect-only. The settings page accepts certificate paths for provided mode, but it never uploads or displays private key material. Mount the files into the container or host first. Environment variables override corresponding saved settings; when an override is present, change the deployment environment instead of the UI. The environment overrides are: - `SEERR_TLS_MODE`: `disabled`, `self-signed`, or `provided`. - `SEERR_HTTPS_PORT`: HTTPS listener port. - `SEERR_TLS_HOSTS`: comma-separated certificate and redirect host list. - `SEERR_TLS_CERT_FILE`, `SEERR_TLS_KEY_FILE`, and optional `SEERR_TLS_CA_FILE`: provided-certificate paths. - `SEERR_HTTP_REDIRECT_TO_HTTPS`: `true` for HTTP `308` redirects or `false` for the non-authenticated HTTPS upgrade response. - `SEERR_ALLOW_HTTP_AUTH`: direct-HTTP authentication when TLS is disabled; defaults to `true` in that mode and can be set to `false` to require HTTPS. If any of these variables are set by a Compose file, systemd unit, chart, or container environment, they take precedence over the corresponding saved setting. Do not inject defaults such as `SEERR_TLS_MODE=disabled` if you want administrators to control transport from the Network page. ## Recommended direct-LAN configuration Use the self-signed mode for a new direct installation. Set every hostname and IP address that users will enter in the browser in `SEERR_TLS_HOSTS`; the certificate is valid only for those subject alternative names. The following example supports both a DNS name and a LAN IP: ```bash mkdir -p /path/to/appdata/config chown -R 1000:1000 /path/to/appdata/config docker run -d \ --name seerr \ --init \ -e PORT=5055 \ -e SEERR_TLS_MODE=self-signed \ -e SEERR_TLS_HOSTS=seerr.home.arpa,192.168.1.20,localhost \ -p 5055:5055 \ -p 5056:5056 \ -v /path/to/appdata/config:/app/config \ --restart unless-stopped \ ghcr.io/snapetech/seerrng:latest ``` Open `https://seerr.home.arpa:5056` or `https://192.168.1.20:5056`. Do not use the HTTP URL for sign-in; port 5055 redirects to HTTPS. ```yaml services: seerr: image: ghcr.io/snapetech/seerrng:latest init: true environment: PORT: 5055 SEERR_TLS_MODE: self-signed SEERR_TLS_HOSTS: seerr.home.arpa,192.168.1.20,localhost ports: - '5055:5055' - '5056:5056' volumes: - /path/to/appdata/config:/app/config restart: unless-stopped ``` ```bash PORT=5055 \ SEERR_TLS_MODE=self-signed \ SEERR_TLS_HOSTS=seerr.home.arpa,192.168.1.20,localhost \ pnpm start ``` The generated files are stored in `CONFIG_DIRECTORY/tls`: - `ca.crt`: the local CA certificate that trusted devices must install. - `ca.key`: the private key used to renew the local server certificate. Do not share it. - `server.crt` and `server.key`: the HTTPS certificate and private key. - `metadata.json`: the generated host list and certificate metadata. The directory is created with restrictive permissions, and generated private keys are written with mode `0600`. The CA and server material persists across restarts, so sessions do not become invalid merely because SeerrNG restarted. ## Trusting the generated certificate On startup SeerrNG logs the HTTPS port, the SHA-256 certificate fingerprint, and the path to `ca.crt`. During setup and login, the UI shows the same fingerprint and offers a download link at `/api/v1/status/tls/ca`. The endpoint returns only the public CA certificate; it never exposes `ca.key` or `server.key`. Verify the fingerprint through a trusted channel before installing the CA. Then install `ca.crt` in the trusted root store of every browser/device that will use SeerrNG. A browser warning is expected until the CA is trusted. Installing the CA on one device does not trust it on another. For a Docker container, the file can also be copied from the persistent volume: ```bash docker cp seerr:/app/config/tls/ca.crt ./seerrng-local-ca.crt ``` The generated CA is private to this SeerrNG installation. It is not a publicly trusted certificate and should not be used as proof of identity on the public internet. ## Using a provided certificate Select **Provided certificate** in **Settings > Network**, or set `SEERR_TLS_MODE=provided`, and provide a matching PEM certificate and private-key file: ```yaml environment: SEERR_TLS_MODE: provided SEERR_TLS_CERT_FILE: /run/secrets/seerr-fullchain.pem SEERR_TLS_KEY_FILE: /run/secrets/seerr-private-key.pem SEERR_HTTPS_PORT: 5056 volumes: - ./certs/seerr-fullchain.pem:/run/secrets/seerr-fullchain.pem:ro - ./certs/seerr-private-key.pem:/run/secrets/seerr-private-key.pem:ro ``` The certificate must contain at least one DNS or IP subject alternative name, and the private key must match it. Put the complete served chain in `SEERR_TLS_CERT_FILE` when the issuing CA requires intermediates. An optional `SEERR_TLS_CA_FILE` can provide a CA bundle to the Node TLS context, but it does not replace serving the intermediate chain in the certificate file. The HTTPS listener defaults to 5056 and can be changed with `SEERR_HTTPS_PORT` or the Network settings page; it must differ from `PORT`. The HTTP listener returns an HTTPS upgrade response until **Redirect HTTP to HTTPS** is enabled. When enabled, it sends a `308` redirect to HTTPS. ## Direct HTTP authentication If TLS is not possible on a trusted, isolated LAN, leave built-in TLS **Disabled**. Direct HTTP authentication is enabled by default and the UI shows a prominent warning. The equivalent environment configuration, with the default made explicit, is: ```yaml environment: SEERR_TLS_MODE: disabled SEERR_ALLOW_HTTP_AUTH: 'true' PORT: 5055 ports: - '5055:5055' ``` This mode keeps `HttpOnly`, SameSite, CSRF, rate limiting, and the other authentication protections, but it permits the session cookie to be sent over HTTP. Anyone able to observe the LAN traffic can steal that cookie. The startup log, setup/login UI, and Network settings page show a prominent warning. The setting is deliberately not inferred from a client IP address or a proxy header. If both `SEERR_ALLOW_HTTP_AUTH=true` and `SEERR_TLS_MODE=self-signed` or `provided` are set, startup fails. When the fallback is enabled, HTTPS requests still receive Secure cookies when SeerrNG can identify the HTTPS transport; configure **Enable Proxy Support** when an HTTPS reverse proxy terminates TLS. ## Reverse proxies and health checks Use either the built-in HTTPS listener or a reverse proxy as the TLS terminator. For a reverse proxy, leave `SEERR_TLS_MODE=disabled` and proxy to the existing HTTP `PORT`; enable SeerrNG's **Enable Proxy Support** setting so the application can safely use the proxy's `X-Forwarded-Proto` value for Secure cookies, HSTS, and CSRF transport decisions. Set `SEERR_ALLOW_HTTP_AUTH=false` if the backend's direct HTTP path must not accept browser sign-in; HTTPS through the proxy still works. In built-in TLS mode, port 5055 is intentionally either redirect-only or upgrade-only, depending on the saved redirect setting. The official container health check automatically switches to the HTTPS listener and uses certificate verification disabled only for that local readiness probe. Custom health checks should make the same mode-aware choice rather than following the HTTP redirect with a browser-style client. If an HTTP request has a Host header that is not in `SEERR_TLS_HOSTS`, SeerrNG returns `421` instead of creating an open redirect. Add every browser-visible hostname and IP to the environment variable before starting the server. ## Troubleshooting sign-in If Jellyfin setup appears to save, does not advance, and a retry reports that the hostname is already configured, the first request probably saved the server details but the browser did not retain the session cookie. This happens when direct HTTP authentication is disabled (`httpAuthAllowed: false`), or when a new transport choice was saved but SeerrNG was not restarted yet. Check the public status endpoint: ```text GET /api/v1/status/tls ``` Before direct HTTP sign-in, the response must report `mode: "disabled"`, `httpAuthAllowed: true`, and `pendingRestart: false`. For HTTPS, open the HTTPS URL after trusting the local CA or configure the reverse proxy to pass `X-Forwarded-Proto: https` with proxy support enabled. After the transport is active, open `/login` and sign in again; the saved Jellyfin server does not need to be entered again. If Plex or local sign-in appears to succeed but the browser immediately returns to the login page: 1. Use the HTTPS URL and HTTPS port shown in the startup log or UI. 2. Trust the local CA when using `self-signed` mode. 3. Confirm the browser is reaching the same hostname listed in `SEERR_TLS_HOSTS`. 4. If using a reverse proxy, enable **Enable Proxy Support** and forward `X-Forwarded-Proto: https`. 5. If a certificate configuration prevents access, set `SEERR_TLS_MODE=disabled` and restart, then correct the saved settings. Set `SEERR_ALLOW_HTTP_AUTH=false` when direct HTTP sign-in must remain disabled; otherwise use HTTPS whenever possible because the default HTTP session path can be observed on the network.