How to Deploy DBX Web Behind a Reverse Proxy with Context Path

TLDR: Set the DBX_PUBLIC_BASE_PATH environment variable to your desired context path (e.g., /dbx) when starting the DBX Web server, then configure your reverse proxy to forward that path to localhost:4224 while preserving the trailing slash on the upstream URL.

DBX Web from the t8y2/dbx repository runs its own HTTP server on port 4224 by default, serving UI assets from the root as documented in the project's README.md. When you need to expose the interface through a reverse proxy under a non-root context path such as /dbx, you must coordinate the application's base URL generation with your proxy's routing rules to prevent broken assets and API errors.

Configuring the DBX Public Base Path

According to the documentation in docs/content/docs/web-api.mdx, DBX Web reads the DBX_PUBLIC_BASE_PATH environment variable at startup to determine the external URL prefix. When set to /dbx, the server automatically prefixes every generated route, static asset reference, and API endpoint with this value.

Set the variable before launching the binary:

export DBX_PUBLIC_BASE_PATH=/dbx
./dbx web

Or inject it via Docker:

docker run -e DBX_PUBLIC_BASE_PATH=/dbx -p 4224:4224 ghcr.io/t8y2/dbx:latest

Without this configuration, DBX Web assumes it is running at the root path (/) and generates absolute URLs that will break when accessed through a reverse proxy subpath.

Nginx Reverse Proxy Configuration

For Nginx, define a location block that matches your context path and forwards requests to the DBX Web process. The configuration must preserve the trailing slash on the proxy_pass directive.

server {
    listen 80;
    server_name example.com;

    location /dbx/ {
        # Forward to DBX Web process on port 4224

        proxy_pass http://127.0.0.1:4224/;
        
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Ensures DBX Web sees the correct base path when generating redirects

        proxy_set_header X-Original-URI $request_uri;
    }
}

Why the trailing slash matters: Nginx concatenates the proxy_pass URL with the remaining request URI. By terminating proxy_pass with a slash (http://127.0.0.1:4224/), Nginx strips the /dbx/ prefix before forwarding, allowing DBX Web's internal router—which expects requests relative to its configured base path—to receive clean paths like /api/... instead of /dbx/api/....

Apache HTTP Server Configuration

If you use Apache with mod_proxy, configure ProxyPass and ProxyPassReverse directives with matching trailing slashes:

<VirtualHost *:80>
    ServerName example.com

    ProxyPreserveHost On
    ProxyPass /dbx/ http://127.0.0.1:4224/
    ProxyPassReverse /dbx/ http://127.0.0.1:4224/
</VirtualHost>

Ensure the DBX_PUBLIC_BASE_PATH=/dbx environment variable is exported in your systemd unit file, Docker container, or startup script before the DBX Web process initializes.

Docker Compose with Traefik

The repository provides a deploy/docker-compose.yml file that includes a commented snippet for reverse-proxy subpath deployment. Set the environment variable and uncomment the labels as shown:

services:
  dbx:
    image: ghcr.io/t8y2/dbx:latest
    ports:
      - "4224:4224"
    environment:
      - DBX_PUBLIC_BASE_PATH=/dbx
    # Uncomment when publishing DBX under a reverse-proxy subpath:

    # labels:

    #   - "traefik.http.routers.dbx.rule=PathPrefix(`/dbx`)"

    #   - "traefik.http.services.dbx.loadbalancer.server.port=4224"

When running behind Traefik or another container-aware reverse proxy, DBX Web generates URLs such as /dbx/api/... and /dbx/static/... automatically based on the DBX_PUBLIC_BASE_PATH setting.

Verifying the Deployment

After starting DBX Web with the environment variable set and configuring your reverse proxy:

1. Visit https://your-domain.com/dbx/ (including the trailing slash).
2. Verify that static assets load without 404 errors in the browser's developer console.
3. Confirm that API calls target /dbx/api/... endpoints rather than /api/....

If assets return 404, verify both that DBX_PUBLIC_BASE_PATH is set to /dbx (with the leading slash) and that your reverse proxy strips the context path before forwarding to port 4224.

Summary

• Set DBX_PUBLIC_BASE_PATH to the desired context path (e.g., /dbx) so DBX Web prefixes all generated URLs correctly.
• Configure the reverse proxy to forward the context path to localhost:4224, ensuring the upstream URL ends with a trailing slash to strip the path prefix.
• Reference docs/content/docs/web-api.mdx for official documentation on the environment variable and deploy/docker-compose.yml for container orchestration patterns.
• Test thoroughly by accessing the full context path URL and monitoring network requests for routing errors.

Frequently Asked Questions

What is the default port for DBX Web?

DBX Web listens on port 4224 by default. When deploying behind a reverse proxy, you forward requests from your public port (typically 80 or 443) to this internal port while keeping port 4224 firewalled from external access.

Why do static assets return 404 errors when using a reverse proxy?

This occurs when the DBX_PUBLIC_BASE_PATH environment variable is unset or when the reverse proxy fails to strip the context path before forwarding. Without the trailing slash in proxy_pass http://127.0.0.1:4224/, Nginx forwards /dbx/static/... to the upstream as /dbx/static/... instead of /static/..., causing DBX Web's router to fail matching the request.

Can I run DBX Web without a context path at the root domain?

Yes. If you deploy at the root path (/), you do not need to set DBX_PUBLIC_BASE_PATH. The application assumes root deployment by default and generates URLs without path prefixes, working with standard reverse proxy configurations that forward / to port 4224.

Does DBX Web support TLS/SSL certificates?

DBX Web handles HTTP traffic only and does not terminate TLS. You should configure TLS at your reverse proxy (Nginx, Apache, or Traefik), which then forwards unencrypted traffic to DBX Web on port 4224, typically over localhost or a private Docker network.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}