You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[FEATURE] Support deployment under a subpath (basePath / base URL) #369
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:
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.
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.
I am picking up the build-time basePath implementation described in the maintainer notes. I will cover prefixed browser/API URLs, authentication redirects and cookies, build/deployment configuration, and regression checks for root and nested paths.
Reacted by Mehmet Cevheri BOZOGLAN and Duc Minh Le
Hi! We’ve seen the build-time BASE_PATH support in #662 and the discussion here.
We host LibreDB under /libredb and would like to use an official prebuilt image without custom builds or runtime patching.
Would you be open to publishing an additional Alpine image variant built with BASE_PATH=/libredb? The tag name is open for discussion. We’d be happy to contribute a PR covering the release pipeline, tests, and documentation.
Thanks for the offer, and for reading #662 closely. We would rather not publish a fixed-prefix image: the prefix is baked in at build time, so a /libredb tag serves exactly one path, and every other prefix would need a variant of its own, each one more leg of signing, scanning and mirroring on every release.
Building it yourself from a release tag is a short, repeatable step, and #2296 documents it in docs/SUBPATH.md: git clone --depth 1 --branch 1.3.0 https://github.com/libredb/libredb-studio.git, then docker build -f Dockerfile.alpine --build-arg BASE_PATH=/libredb ... from that checkout. I verified it on 1.3.0 with your prefix. One trap worth knowing: building straight from the Git URL (docker build <url>#1.3.0) skips .dockerignore and runs out of heap, so build from a checkout.
If more deployments ask for the same prefix, we will revisit publishing one. Comments on #2296 are welcome before it merges.
Thanks for the clarification. We explored a possible middle ground: one image containing two prebuilt profiles — root (/) and /libredb, selected at startup. This would cover both dedicated-domain and subpath deployments with the same published artifact.
Our local proof of concept:
Builds /libredb using the existing BASE_PATH support, without source changes.
Shares identical dependencies/assets and Brotli-compresses the differing compiled files.
Restores the exact prefixed build at startup, verifying every file with SHA256 — no placeholder replacement or rewriting of JS/HTML/RSC.
Adds 0.85 MiB (+0.63%) to the compressed official Alpine image.
Both profiles passed local browser checks: login, queries, RBAC, deep links/reload and logout. The trade-off is approximately 80 MiB of temporary files and 150 ms to materialize the prefixed profile.
This was tested on linux/amd64 only. Both profiles still require builds and tests, but there would be one image to publish, sign, scan and mirror.
Thanks for building and measuring this, it is a careful piece of work and the numbers are clear. We will not take it, for reasons about the shape rather than the quality. The prefixed profile does not exist in the image as files: it is assembled at startup from compressed differences into /tmp, so the files that run are not the files the image ships, and debugging has to start by asking which tree is live. Even without that step, a second fixed profile only covers /libredb, while the same variable would suggest any prefix works, and it doubles the build and test matrix on every release for one path. We want Studio's behaviour to be visible in what ships
Activity
fix(chart): finish the Gateway API route surface (#366)
fix(chart): finish the Gateway API route surface (#366) (#399)
cevheri commentedon Aug 16, 2026
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.tssets neitherbasePathnorassetPrefix, so there is zero support today.The central finding first, because it decides the shape of any fix: Next.js
basePathis 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 aBASE_PATH(orBASE_URL) environment variable on the prebuiltghcr.io/libredb/libredb-studioimage 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
StripPrefixfails on the second request: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_urlat 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_PATHbuild arg, meaning you build your own image or we publish a variant. The honest surface, so the size is visible: 40 root-relativefetch("/api/...")call sites across 23 files; 15 root-relativerouter.push/router.replace; 11NextResponse.redirectin middleware and API routes; thepath: "/"cookie insrc/lib/auth.tsandsrc/app/api/auth/oidc/login/route.ts; the OIDC redirect and post-logout URIs; thesrc/proxy.tsmatcher; the/api/db/healthprobes in the chart and the compose healthcheck; the chart's ingress and HTTPRoute paths; and the E2E suite.next/linkand 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
N3indocs/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 commentedon Aug 16, 2026
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
N3indocs/BACKLOG.md.SyedMuhamadYasir commentedon Sep 8, 2026
I am picking up the build-time basePath implementation described in the maintainer notes. I will cover prefixed browser/API URLs, authentication redirects and cookies, build/deployment configuration, and regression checks for root and nested paths.
del000 commentedon Nov 14, 2026
Hi! We’ve seen the build-time
BASE_PATHsupport in #662 and the discussion here.We host LibreDB under
/libredband would like to use an official prebuilt image without custom builds or runtime patching.Would you be open to publishing an additional Alpine image variant built with
BASE_PATH=/libredb? The tag name is open for discussion. We’d be happy to contribute a PR covering the release pipeline, tests, and documentation.Would this approach work for you?
cevheri commentedon Nov 14, 2026
Thanks for the offer, and for reading #662 closely. We would rather not publish a fixed-prefix image: the prefix is baked in at build time, so a
/libredbtag serves exactly one path, and every other prefix would need a variant of its own, each one more leg of signing, scanning and mirroring on every release.Building it yourself from a release tag is a short, repeatable step, and #2296 documents it in
docs/SUBPATH.md:git clone --depth 1 --branch 1.3.0 https://github.com/libredb/libredb-studio.git, thendocker build -f Dockerfile.alpine --build-arg BASE_PATH=/libredb ...from that checkout. I verified it on 1.3.0 with your prefix. One trap worth knowing: building straight from the Git URL (docker build <url>#1.3.0) skips.dockerignoreand runs out of heap, so build from a checkout.If more deployments ask for the same prefix, we will revisit publishing one. Comments on #2296 are welcome before it merges.
docs(subpath): explain why a prebuilt image cannot take the prefix at…
del000 commentedon Nov 15, 2026
Thanks for the clarification. We explored a possible middle ground: one image containing two prebuilt profiles — root (
/) and/libredb, selected at startup. This would cover both dedicated-domain and subpath deployments with the same published artifact.Our local proof of concept:
/libredbusing the existingBASE_PATHsupport, without source changes.Both profiles passed local browser checks: login, queries, RBAC, deep links/reload and logout. The trade-off is approximately 80 MiB of temporary files and 150 ms to materialize the prefixed profile.
This was tested on
linux/amd64only. Both profiles still require builds and tests, but there would be one image to publish, sign, scan and mirror.Would you consider this fixed-profile approach?
cevheri commentedon Nov 15, 2026
Thanks for building and measuring this, it is a careful piece of work and the numbers are clear. We will not take it, for reasons about the shape rather than the quality. The prefixed profile does not exist in the image as files: it is assembled at startup from compressed differences into /tmp, so the files that run are not the files the image ships, and debugging has to start by asking which tree is live. Even without that step, a second fixed profile only covers /libredb, while the same variable would suggest any prefix works, and it doubles the build and test matrix on every release for one path. We want Studio's behaviour to be visible in what ships
docs(subpath): show how to build a prefixed image for a release (#2296)