Skip to content

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

Closed

Description

@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

Activity

  1. cevheri commented on Aug 16, 2026

    @cevheri
    Member

    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.

  2. cevheri commented on Aug 16, 2026

    @cevheri
    Member

    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.

  3. SyedMuhamadYasir commented on Sep 8, 2026

    @SyedMuhamadYasir
    Contributor

    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.

  4. del000 commented on Nov 14, 2026

    @del000

    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.

    Would this approach work for you?

  5. cevheri commented on Nov 14, 2026

    @cevheri
    Member

    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.

  6. del000 commented on Nov 15, 2026

    @del000

    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.

    Would you consider this fixed-profile approach?

  7. cevheri commented on Nov 15, 2026

    @cevheri
    Member

    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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions