Skip to content

Reverse Proxy Setup

iongpt edited this page Nov 17, 2026 · 5 revisions

Reverse Proxy Configuration

Boxarr supports running behind a reverse proxy at a custom path (e.g., /boxarr instead of /). This is useful when you want to access multiple services through a single domain.

With a URL base set, Boxarr serves its pages, API and static files under /<url base>/ itself, so the proxy must pass the path through unchanged. Do not strip the prefix: if the proxy strips it, the pages load without their stylesheets and scripts.

Setting the URL Base

The URL base is configured via the BOXARR_URL_BASE environment variable. Do not include leading or trailing slashes.

Docker Compose Example

version: '3.8'

services:
  boxarr:
    image: ghcr.io/iongpt/boxarr:latest
    container_name: boxarr
    ports:
      - 8888:8888
    volumes:
      - ./config:/config
    environment:
      - TZ=America/New_York
      - BOXARR_URL_BASE=boxarr  # Access at http://your-server/boxarr/
    restart: unless-stopped

Command Line Example

BOXARR_URL_BASE=boxarr python -m src.main

Nginx Configuration

location /boxarr/ {
    # No URI after the port, so nginx keeps the /boxarr/ prefix
    proxy_pass http://localhost:8888;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Traefik Configuration

# Docker labels for Traefik
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.boxarr.rule=Host(`your-domain.com`) && PathPrefix(`/boxarr`)"
  - "traefik.http.services.boxarr.loadbalancer.server.port=8888"

Do not add a stripprefix middleware.

Caddy Configuration

your-domain.com {
    handle /boxarr* {
        reverse_proxy localhost:8888
    }
}

Use handle, not handle_path: handle_path strips the prefix.

Important Notes

  1. Configuration is read-only in UI: For safety, the URL base cannot be changed through the web interface. This prevents accidental lockouts. Set it with the BOXARR_URL_BASE environment variable, or with url_base under boxarr: in /config/local.yaml (Boxarr reads /config/config.yaml instead only while there is no local.yaml); the environment variable wins if both are set. Saving the setup page keeps a url_base set in the file.

    boxarr:
      url_base: boxarr
  2. Restart required: After setting or changing BOXARR_URL_BASE, you must restart Boxarr for the changes to take effect.

  3. Accessing the application:

    • Without URL base: http://your-server:8888/
    • With URL base "boxarr": http://your-server:8888/boxarr/
    • Behind reverse proxy: https://your-domain.com/boxarr/
  4. Recovery: If you're locked out due to incorrect configuration:

    # Reset to root path
    BOXARR_URL_BASE="" python -m src.main
    
    # Or edit your docker-compose.yml and remove the BOXARR_URL_BASE line
    # (or remove url_base from /config/local.yaml), then restart
  5. No proxy changes needed for the cross-site check: Boxarr refuses changes that a browser sends from another website. Its own pages mark their requests with a custom X-Boxarr-Request header, and nginx, Traefik and Caddy forward custom request headers by default, so the configurations above work unchanged. Only a proxy you configured to strip unknown request headers must let X-Boxarr-Request through. If it does not, saving settings and the other buttons can fail with a 403 "Cross-site request blocked" message that names this header, typically over plain http when the Host header Boxarr receives differs from the address in the browser.

Sign-in Behind a Reverse Proxy

Since v2.4.0 Boxarr can ask for a sign-in (Authentication). Behind a reverse proxy, three things matter.

URL Base and the Login Page

  • A signed-out browser is sent to /<url base>/login?next=<the page it asked for>, and comes back there after signing in.
  • The sign-in cookie's Path is the URL base: /boxarr/, or / without one.

Both come from BOXARR_URL_BASE. So the proxy must pass the prefix through unchanged, as above, and must not rewrite the cookie's Path (nginx proxy_cookie_path). If they do not match, the login page signs you in but says the cookie did not come back, for example the sign-in cookie is for /boxarr/ and this page is at /. Set BOXARR_URL_BASE to the path the browser sees.

A dashboard on another site (Organizr, Homarr) that shows Boxarr in a frame cannot keep it signed in: the browser blocks the cookie in a cross-site frame. Open Boxarr in its own tab, or serve both from the same site.

Trusted Proxies

Under Forms, sign-in works behind a proxy without more settings. List the proxy's address in BOXARR_AUTH_TRUSTED_PROXIES (or Settings → Security → Trusted proxies) so that sign-in sees the browser behind it:

  • The sign-in throttle and the Failed sign-in from <address> log line see the browser's address. Without the list, every browser shares the proxy's address and its count of failures.
  • With Secure cookie on auto, the cookie is marked Secure when the proxy says the browser is on https (X-Forwarded-Proto).

Sign-in believes X-Forwarded-For and X-Forwarded-Proto only from the listed addresses. FORWARDED_ALLOW_IPS does not count. The nginx example above sends both headers; Traefik and Caddy send them by default.

    environment:
      - BOXARR_URL_BASE=boxarr
      - BOXARR_AUTH_TRUSTED_PROXIES=172.20.0.5   # the proxy's address, as Boxarr sees it

To find the address, open Settings → Security through the proxy. It shows where the request came from, for example This request: from 172.20.0.5 (http), not through a trusted proxy., and names the address to add when it sends X-Forwarded-For without being trusted. *, 0.0.0.0/0 and networks broader than /8 (IPv4) or /16 (IPv6) are never trusted. See Trusted proxies.

External: the Proxy Signs People In

If your proxy already signs people in (Authelia, Authentik, oauth2-proxy), set Boxarr to External. Boxarr then lets in every request whose connection comes from a trusted proxy, and refuses the rest, except the API key, the widgets and the health check.

    environment:
      - BOXARR_URL_BASE=boxarr
      - BOXARR_AUTH_METHOD=external
      - BOXARR_AUTH_TRUSTED_PROXIES=172.20.0.5
location /boxarr/ {
    auth_request /authelia;              # your proxy's own sign-in, set up as its docs say
    proxy_pass http://boxarr:8888;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Before you rely on it:

  • Trust only the proxy's own address. Where Docker publishes Boxarr's port, every client can arrive from the Docker gateway's address, and trusting the gateway lets everyone in. Put the proxy and Boxarr on one Docker network, and trust the proxy's address there. Do not publish Boxarr's port unless you need it (for the widgets, below), and never trust the gateway.
  • Do not skip the proxy's sign-in for /api/*. Every request through the proxy counts as signed in, so such a rule opens the whole API to anyone who reaches the proxy. Only changes under /api/auth/ stay guarded, and only by Boxarr's own password when one is set. Scripts should send the API key instead.
  • The widget paths. A widget request through the proxy passes without the widget token. Boxarr cannot tell that the proxy skipped its sign-in, so if the proxy lets /boxarr/api/widget and /boxarr/api/widget/json through without it, they are public, token or not. To keep the token, embed Boxarr's own address, one that does not go through the proxy. Settings → Security says so when the widgets need a token.

See External for switching from Settings, passwords under External and what is logged.

Clone this wiki locally