feat: support deployment behind a reverse proxy under a sub-path

[Pfannkuchensack]

Summary

The web frontend derived all URLs from window.location.origin and used hardcoded paths (/api, /ws/socket.io, /locales, /openapi.json), so running Invoke behind a reverse proxy under a sub-path (e.g. https://host/invoke/) broke because the prefix was lost.

Frontend: adds a shared helper (common/util/baseUrl.ts) that auto-detects the deployment prefix from the entry bundle URL (import.meta.url), relying on Vite's existing base: './'. getBaseUrl(), the socket.io path, the i18n loadPath, the openapi fetch and the React Router basename now all use it. At the domain root the prefix is empty, so behavior is byte-identical to before. Covered by unit tests.

Backend: adds an opt-in base_url setting (plus forwarded_allow_ips). When set, the app is wrapped in SubPathASGIMiddleware, which strips the prefix from the request path and advertises root_path, handling both proxy styles (preserve and strip). uvicorn's root_path is intentionally not used, because it prepends the prefix to the request path and breaks the preserve case (the prefix would appear twice). Default (unset) leaves existing installs completely unchanged.

Two deployment scenarios are supported:

• Strip proxy (proxy removes the sub-path before forwarding): works with zero backend config via frontend auto-detection. Setting base_url is optional but recommended so /docs + openapi URLs are correct.
• Preserve proxy (proxy forwards the sub-path unchanged): requires base_url so the middleware can strip the prefix for routing.

QA Instructions

Tested end-to-end with Docker + a Caddy reverse proxy in three configurations; every endpoint was checked for the correct content type and body (not just status code):

Configuration	UI	API (real JSON)	openapi.json	locales	/docs	WebSocket
Preserve proxy + base_url=/invoke	✅	✅	✅	✅	✅ (refs /invoke/openapi.json)	✅ (valid sid)
Strip proxy + base_url=/invoke	✅	✅	✅	✅	✅	✅
Strip proxy, zero-config (base_url unset)	✅	✅	✅	✅	–	✅

The frontend prefix-detection logic is also covered by unit tests (baseUrl.test.ts).

To reproduce locally (production build required — the dev server has no /assets/ segment, so auto-detection is a no-op there):

Strip proxy (Caddy):

:8080 {
    handle_path /invoke/* {
        reverse_proxy 127.0.0.1:9090
    }
    redir /invoke /invoke/ 308
}

Leave base_url unset (or set base_url: /invoke to also fix /docs).

Preserve proxy (nginx):

location /invoke/ {
    proxy_pass http://127.0.0.1:9090/invoke/;   # note: NO trailing-slash stripping
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
location = /invoke { return 301 /invoke/; }

Set base_url: /invoke and forwarded_allow_ips: <proxy-ip> in invokeai.yaml.

Then browse http://localhost:8080/invoke/ and confirm: UI loads, generations stream progress (websocket), language switching loads locales, and a reload restores client state. Also verify a regression check at the domain root (http://localhost:9090/) still works with base_url unset.

Merge Plan

Normal merge. No DB schema or redux slice changes. The config schema gains two opt-in fields (base_url, forwarded_allow_ips); both default to a no-op, so no migration is needed.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable)
• ❗Changes to a redux slice have a corresponding migration
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

[lstein]

Thanks — this is a well-constructed PR. The import.meta.url auto-detection on the frontend is elegant and unit-tested, the base_url validator normalizes correctly (I exercised '/invoke/', '//invoke//', ' /x ', '', '/' — all behave as documented), defaults are a strict no-op, and the dual proxy-style handling works for the main flows. I ran the new frontend tests (6/6 pass) and exercised the middleware against Starlette 0.48/FastAPI with a TestClient to verify behavior empirically.

Requesting changes for one functional gap plus two confirmed backend edge cases; details in the inline comments where the code is in the diff.

1. Login/setup flows break under a sub-path (blocking)

The PR sets the React Router basename, but two auth components navigate with hard-coded absolute paths that bypass it (these files aren't in the diff, so noting here rather than inline):

• invokeai/frontend/web/src/features/auth/components/LoginPage.tsx:65 — window.location.href = '/app' (the deliberate full reload for multiuser state isolation)
• invokeai/frontend/web/src/features/auth/components/AdministratorSetup.tsx:63 — window.location.href = '/login'

Under https://host/invoke/, completing login or admin setup navigates to https://host/app / https://host/login — outside the proxied prefix, typically a proxy 404. Since these are the entry points when auth is enabled, sub-path support is broken for multiuser installs. Fix is small and keeps the full-reload semantics:

window.location.href = `${getBasePath()}/app`;  // and '/login' in AdministratorSetup

2. Server-generated redirects lose the prefix (confirmed empirically)

Because the middleware strips base_path from scope["path"] while Starlette builds redirect URLs from scope["path"] alone, every server-generated redirect drops the prefix. TestClient results with base_url=/invoke:

GET /invoke/api/v1/images        -> 200                                        (routing ✓)
GET /invoke/api/v1/boards        -> 307 Location: http://host/api/v1/boards/   (prefix lost)
GET /invoke/?__theme=dark        -> 307 Location: /                            (prefix lost)

The SPA always sends canonical URLs so it won't hit the trailing-slash 307s, but direct API consumers will — and the ?__theme=dark case is exactly what RedirectRootWithQueryStringMiddleware exists for, and it now lands the user at the domain root. See the inline comment on SubPathASGIMiddleware for a suggested fix (prepend instead of strip).

3. base_url colliding with a real route prefix silently bricks the app (confirmed)

With base_url: /api, both delivery styles 404: /api/v1/images gets eaten by the strip logic, and /api/api/v1/images gets double-stripped by Starlette's get_route_path (which removes root_path from path a second time). Same for /ws, /static, /docs, /redoc, /locales, /assets, /openapi.json. The failure mode is a completely dead server with no hint why — see inline comment on the validator.

Minor

• No backend tests for the middleware or validator, and both are trivially unit-testable — given the subtle proxy-style matrix above, a small test would protect this from regressing. Happy to share the TestClient harness I used for the results above.

[lstein]

See inline comments above for issues picked up during code review.

[lstein]

All review comments addressed. LGTM

[lstein]

Pushed a merge of main to resolve the conflict with #9358 (per-user socket event scoping), which landed after your last merge of main.

Also: nice catch on the engine.io handshake 404 — the prepend approach I suggested did introduce that, and folding base_url into socketio_path is the right fix. All review findings are addressed; approval incoming.