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

> Deploy DBX Web behind a reverse proxy with context path. Set DBX_PUBLIC_BASE_PATH and configure your proxy to forward requests efficiently.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/t8y2/dbx/blob/main/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:

```bash
export DBX_PUBLIC_BASE_PATH=/dbx
./dbx web

```

Or inject it via Docker:

```bash
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.

```nginx
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:

```apache
<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`](https://github.com/t8y2/dbx/blob/main/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:

```yaml
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`](https://github.com/t8y2/dbx/blob/main/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.