REVERSE PROXY

Reverse Proxy & Subdirectory Deployment

Questarr can be served from a subdirectory (e.g. https://xxx.domain.com/Questarr) behind a reverse proxy, instead of owning its own subdomain or root path.

How it works

• The client build uses relative asset paths by default and detects its own base path at runtime, so it doesn’t need to know about the subdirectory in advance.
• The server understands an optional QUESTARR_BASE_PATH environment variable. When set, it mounts the entire app (API, WebSocket, and static assets) under that prefix, so a reverse proxy can forward requests straight through without rewriting the path.

Setting QUESTARR_BASE_PATH is only required if you want Questarr itself to own the prefix (recommended — see below). If you’d rather have your reverse proxy strip the prefix before forwarding to Questarr, you can leave QUESTARR_BASE_PATH unset; the client’s runtime base-path detection adapts either way.

1. Configure Questarr

Set QUESTARR_BASE_PATH to the path you want to serve from (leading slash, no trailing slash — e.g. /Questarr):

Docker Compose:

services:
  app:
    image: ghcr.io/doezer/questarr:latest
    environment:
      - QUESTARR_BASE_PATH=/Questarr
    # ...

docker run:

docker run -e QUESTARR_BASE_PATH=/Questarr ghcr.io/doezer/questarr:latest

npm (non-Docker): add QUESTARR_BASE_PATH=/Questarr to your .env file.

With this set, Questarr:

• Serves the app and all /api/* routes under /Questarr/*
• Redirects the unprefixed root (/) to /Questarr/
• Keeps /api/health reachable unprefixed too, so container healthchecks (which talk to the container directly, not through the proxy) keep working unmodified
• Serves the WebSocket (Socket.IO) connection at /Questarr/socket.io/

2. Configure your reverse proxy

Point requests under the prefix at the Questarr container/process, without stripping the prefix — Questarr expects to see it.

nginx

app below is the Compose service name from this repo’s docker-compose.yml — substitute your own container/service name if it differs. nginx’s prefix match only covers /Questarr/..., so add an exact-match redirect for the bare /Questarr (no trailing slash) case too:

location = /Questarr {
    return 301 /Questarr/;
}

location /Questarr/ {
    proxy_pass http://app:5000/Questarr/;
    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;

    # Required for Socket.IO (real-time download/notification updates)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Traefik (labels)

labels:
  - "traefik.http.routers.questarr.rule=Host(`xxx.domain.com`) && PathPrefix(`/Questarr`)"
  - "traefik.http.services.questarr.loadbalancer.server.port=5000"

No StripPrefix middleware needed — Questarr handles the prefix itself.

Caddy

Caddy’s /Questarr/* matcher is exact-prefix and won’t match the bare /Questarr (no trailing slash) request, so redirect it explicitly:

xxx.domain.com {
    redir /Questarr /Questarr/ permanent
    reverse_proxy /Questarr/* app:5000
}

3. Verify

Visit https://xxx.domain.com/Questarr/. Login, navigation, API calls, and real-time download/notification updates should all work normally under the prefix.

Notes

• QUESTARR_BASE_PATH accepts letters, numbers, hyphens, underscores, and slashes only (e.g. /Questarr, /games/questarr). Invalid values fail startup with a clear error, the same way other misconfigured environment variables do.
• Changing QUESTARR_BASE_PATH only affects the running server — no rebuild is required, since the pre-built Docker image resolves the base path at runtime rather than baking it into the client bundle at build time.