Deploy dbportal under a subpath

dbportal can run at /libredb, /tools/libredb, or /~/libredb behind a reverse proxy. Set BASE_PATH when building. Next.js bakes this prefix into routes and browser bundles; setting it only on a prebuilt image cannot relocate that image. The published images use /.

Use a leading slash and no trailing slash. Empty or / selects the root. Path segments may contain letters, digits, ., _, ~, and -; dot segments, encoded paths, query strings, fragments, backslashes, and repeated slashes are rejected during the build.

Build from source

Keep the same value for build and next start:

export BASE_PATH=/tools/libredb
bun install --frozen-lockfile
bun run build
bun start

With Docker, build a custom image from the source revision containing subpath support:

docker build --build-arg BASE_PATH=/tools/libredb -t studio-subpath:local .
docker run --rm -p 3000:3000 --env-file .env.local studio-subpath:local

The build uses the prefix from the build arg. Supply your normal runtime authentication, storage, and LLM settings as usual. BASE_PATH is not a replacement for a public origin or for ALLOWED_ORIGINS; that setting still takes origins such as https://example.com.

The source docker-compose.yml forwards BASE_PATH as a build arg:

BASE_PATH=/tools/libredb docker compose up --build

When using docker-compose.example.yml, select your custom image and set the same BASE_PATH in Compose’s environment so its health check uses the built path.

Preserve the prefix at the reverse proxy

Forward /tools/libredb and everything below it with the path intact. Do not use Traefik StripPrefix, an Nginx rewrite, or an HTTPRoute URLRewrite to remove the prefix. For example, an Nginx upstream without a URI suffix preserves the original path:

location ~ ^/tools/libredb(?:/|$) {
    proxy_pass http://studio:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

For Traefik, match PathPrefix(`/tools/libredb`) and forward to dbportal without a strip-prefix middleware. Restrict the rule to your intended hostname as usual. Assets, API calls, streamed agent responses, and native authentication redirects all use the configured prefix. Next’s router and Link apply it automatically. dbportal has no WebSocket endpoint to configure.

Helm and Gateway API

Build and publish your own image with the prefix first. Then use matching chart values:

image:
  repository: registry.example.com/studio-subpath
  tag: my-build
config:
  basePath: /tools/libredb

ingress:
  enabled: true
  hosts:
    - host: example.com
      paths:
        - path: /tools/libredb
          pathType: Prefix

config.basePath prefixes the chart’s default startup, readiness, and liveness health paths. It does not set a runtime app environment variable. Explicit custom probe paths, exec probes, and TCP probes are preserved. A mismatched image and chart prefix fails readiness.

For a Gateway API deployment, use an HTTPRoute match with the same prefix and your cluster’s actual Gateway reference:

route:
  main:
    enabled: true
    parentRefs:
      - name: my-gateway
    hostnames:
      - example.com
    matches:
      - path:
          type: PathPrefix
          value: /tools/libredb

Do not add a rewrite filter. If you use external health checks, request /tools/libredb/api/db/health.

Authentication and editor assets

Register the full OIDC callback URL, for example https://example.com/tools/libredb/api/auth/oidc/callback, and allow the logout return URL https://example.com/tools/libredb/login at your identity provider. Session and OIDC state cookies use /tools/libredb as their path, including when they are removed.

The default Monaco asset URL becomes /tools/libredb/monaco/vs. An explicit NEXT_PUBLIC_MONACO_VS_PATH override is used exactly as configured, including an external asset origin; do not add the prefix a second time.

For the embedded npm library, the host application’s routing remains its responsibility. Standalone builds publish the internal NEXT_PUBLIC_BASE_PATH value from BASE_PATH; it is not a separate operator setting.

Verification

bun run test:e2e:base-path builds at /~/libredb, starts a local path-preserving proxy that returns 404 outside that prefix, and tests login, RBAC, cookie deletion, a real SQLite query, origin checks, OIDC error redirects, and self-hosted editor assets in Chromium. Run it after the ordinary E2E suite; the two configurations build different versions of .next.