[FEATURE] Support deployment under a subpath (basePath / base URL)

[ducminhle]

Is your feature request related to a problem?

LibreDB Studio currently appears to assume deployment at the root path (/). In environments where applications are published behind a reverse proxy using a path prefix, such as:

• https://example.com/libredb
• https://example.com/tools/libredb
• https://example.com/~/libredb

routing, authentication redirects, static assets, API endpoints, and websocket connections may not work correctly.

This makes it difficult to deploy LibreDB Studio in organizations that standardize on path-based routing rather than dedicated subdomains.

Describe the solution you'd like

BASE_PATH=/libredb

or

BASE_URL=https://example.com/~/libredb

When configured, all routes, redirects, static assets, API endpoints, and websocket URLs should automatically respect the configured prefix.

Describe alternatives you've considered

• Subdomain, but is not always possible in environments with DNS restrictions, centralized ingress configurations, or internal application portals that require path-based routing.

Use Case

• Our environment hosts multiple self-hosted applications behind a single domain using a reverse proxy.
  Ex:

https://example.com/grafana
https://example.com/libredb

Additional Context

None

Implementation Notes (Optional)

None

Related Issues

None

[cevheri]

Thanks for filing this, and for the concrete use case. This is a real gap, not a niche one: path-based routing behind a single ingress is the normal shape for internal application portals, and plenty of teams cannot get a subdomain at all. Your read of the current state is correct - next.config.ts sets neither basePath nor assetPrefix, so there is zero support today.

The central finding first, because it decides the shape of any fix: Next.js basePath is resolved at build time, not at runtime. The build emits HTML and JS with asset and route URLs already written into them - /_next/static/chunks/..., the route manifests, the client router's own base. There is no supported runtime override and no place to inject one after the fact. So a BASE_PATH (or BASE_URL) environment variable on the prebuilt ghcr.io/libredb/libredb-studio image cannot work. Not "does not work yet" - it is the wrong layer.

The obvious workaround does not rescue it either, so let me kill it explicitly. A reverse-proxy StripPrefix fails on the second request:

1. GET https://example.com/libredb/        -> proxy strips /libredb -> app sees GET /
2. app returns HTML referencing /_next/static/chunks/main.js   (root-relative, baked in)
3. browser resolves that against the origin -> GET https://example.com/_next/static/chunks/main.js
4. that path never matches the /libredb router rule -> 404 (or your portal's index)

Same failure for /api/* calls and for the login redirect. The result is a blank page behind a wall of 404s.

On the Grafana comparison: it is a fair one, and the difference is real rather than a dodge. Grafana is a Go server that renders its index server-side, so it can read root_url at process start and rewrite asset URLs on every response. A statically built Next.js app has already emitted those URLs before the container starts. Same feature, different shape.

One sharp edge worth naming regardless of what happens here: the chart already accepts ingress.hosts[].paths[].path: /libredb. The install succeeds, the Ingress is valid, and the app is simply unreachable. That is the same silent-no-op class as #366 item 2, and it deserves a guard whether or not basePath itself ever ships.

What is achievable is a build-time BASE_PATH build arg, meaning you build your own image or we publish a variant. The honest surface, so the size is visible: 40 root-relative fetch("/api/...") call sites across 23 files; 15 root-relative router.push / router.replace; 11 NextResponse.redirect in middleware and API routes; the path: "/" cookie in src/lib/auth.ts and src/app/api/auth/oidc/login/route.ts; the OIDC redirect and post-logout URIs; the src/proxy.ts matcher; the /api/db/health probes in the chart and the compose healthcheck; the chart's ingress and HTTPRoute paths; and the E2E suite. next/link and app-router navigation prefix automatically; fetch, middleware redirects and cookie paths do not. One piece of good news on your list: there is no WebSocket code in the app today, so that part is free.

Roadmap position, without over-promising: accepted, but not next up. The one-click platform listings we are prioritising hand out subdomains, so this is not on that critical path. It is recorded as backlog item N3 in docs/BACKLOG.md (landing with #399) with the build-time constraint written down, so nobody has to rediscover it.

The offer, specific rather than polite: you have the only environment that can actually verify this - Traefik with path-based routing behind a single domain - and you have already carried a chart PR through CI. If you want it, it is yours, and I will answer questions on any part of the surface above. Genuinely no obligation if you would rather not, and I will not treat silence as a no forever.

[cevheri]

The shared-edge theme this sits in - #362, #366 and this issue - was briefly tracked in #400, which is now closed as redundant: this issue is the live item, and the build-time constraint above is recorded as backlog entry N3 in docs/BACKLOG.md.