Repository navigation
Reverse Proxy Setup
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.
The URL base is configured via the BOXARR_URL_BASE environment variable. Do not include leading or trailing slashes.
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-stoppedBOXARR_URL_BASE=boxarr python -m src.mainlocation /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;
}# 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.
your-domain.com {
handle /boxarr* {
reverse_proxy localhost:8888
}
}Use handle, not handle_path: handle_path strips the prefix.
-
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_BASEenvironment variable, or withurl_baseunderboxarr:in/config/local.yaml(Boxarr reads/config/config.yamlinstead only while there is nolocal.yaml); the environment variable wins if both are set. Saving the setup page keeps aurl_baseset in the file.boxarr: url_base: boxarr
-
Restart required: After setting or changing
BOXARR_URL_BASE, you must restart Boxarr for the changes to take effect. -
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/
- Without URL base:
-
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
-
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-Requestheader, 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 letX-Boxarr-Requestthrough. 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 theHostheader Boxarr receives differs from the address in the browser.
Since v2.4.0 Boxarr can ask for a sign-in (Authentication). Behind a reverse proxy, three things matter.
- 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.
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 itTo 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.
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.5location /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/widgetand/boxarr/api/widget/jsonthrough 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.