# How to Deploy DBX with Docker: A Complete Self-Hosting Guide

> Deploy DBX with Docker using this complete self-hosting guide. Learn to package the Vue 3 frontend and Rust backend into a minimal Debian image for easy setup.

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

---

**DBX can be deployed as a self-hosted web service using a multi-stage Docker build that packages a Vue 3 frontend and Rust backend into a minimal Debian image, exposing port 4224 and storing persistent data in `/app/data`.**

The t8y2/dbx repository provides a modern file-sharing and URL shortening platform that you can self-host using Docker. Deploying DBX with Docker leverages a sophisticated multi-stage build process defined in `deploy/Dockerfile` to create a lightweight, production-ready container that supports both amd64 and arm64 architectures.

## Understanding the Multi-Stage Dockerfile

The official Docker image is built using a multi-stage approach that separates the build environment from the final runtime. This strategy minimizes the attack surface and reduces the final image size by excluding compilers and build tools from the production container.

### Stage 1: Building the Frontend

The first stage uses a **Node 22-slim** base image to compile the Vue 3 + TypeScript frontend. According to the source code in `deploy/Dockerfile` (lines 3-13), this stage installs dependencies using **pnpm** and generates optimized static assets that are output to the `dist` directory.

### Stage 2: Compiling the Rust Backend

The second stage handles the **Rust backend** (`dbx-web`) compilation using a Rust 1-bookworm image. As implemented in `deploy/Dockerfile` (lines 14-70), the build process first compiles the Cargo manifests to cache dependencies, then cross-compiles the application for the target architecture (amd64 or arm64). The resulting binary is placed in `/out/linux/<arch>`.

### Stage 3: Creating the Runtime Image

The final stage constructs the production runtime from a minimal **Debian bookworm-slim** base. The `deploy/Dockerfile` (lines 72-87) copies the compiled `dbx-web` binary to `/usr/local/bin/` and the built static files to `/app/static`. The container automatically sets `DBX_STATIC_DIR` and `DBX_DATA_DIR`, exposes port 4224, and configures `dbx-web` as the entrypoint.

## Configuration Options

DBX behavior is controlled through environment variables. The most critical settings are:

- **`DBX_PASSWORD`** — Sets the web UI login password (required unless authentication is disabled)
- **`DBX_PUBLIC_BASE_PATH`** — Configures the base path when running behind a reverse proxy sub-path (e.g., `/dbx`)
- **`DBX_STATIC_DIR`** — Path to static assets (auto-set to `/app/static` in the official image)
- **`DBX_DATA_DIR`** — Path to persistent data storage (auto-set to `/app/data` in the official image)

## Deployment Methods

### Method 1: Using Docker Run

For a quick start, pull the pre-built multi-arch image `t8y2/dbx` from Docker Hub and run it with a named volume for persistence:

```bash
docker run -d \
  --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  -e DBX_PASSWORD=changeme \
  t8y2/dbx

```

The container will be reachable at `http://localhost:4224`. If you need a custom base path, add `-e DBX_PUBLIC_BASE_PATH=/mydbx`.

### Method 2: Using Docker Compose

The recommended approach for production deployments uses the provided [`deploy/docker-compose.yml`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) file. This declarative configuration defines the service, maps port 4224, and creates a named volume `dbx-data` mounted to `/app/data` for state persistence:

```yaml
services:
  dbx:
    build:
      context: .
      dockerfile: deploy/Dockerfile
    ports:
      - "4224:4224"
    environment:
      - DBX_PASSWORD=changeme
    volumes:
      - dbx-data:/app/data
    restart: unless-stopped

volumes:
  dbx-data:

```

Deploy using:

```bash
docker compose -f deploy/docker-compose.yml up -d

```

### Method 3: Building from Source

To build the image locally from the repository:

```bash
git clone https://github.com/t8y2/dbx.git
cd dbx
docker compose -f deploy/docker-compose.yml up --build -d

```

This command builds the image using the multi-stage Dockerfile and starts the container immediately.

## Data Persistence and Storage

The container stores all persistent data—including the SQLite database, configuration files, and uploaded files—in `/app/data`. To ensure your data survives container restarts, you must mount this directory as a Docker volume. The [`deploy/docker-compose.yml`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) (lines 12-14) demonstrates this by creating a named volume `dbx-data` that maps to `/app/data` in the container.

## Summary

- The **multi-stage Dockerfile** at `deploy/Dockerfile` optimizes the build by separating frontend compilation, Rust compilation, and final runtime into distinct stages
- Use the official **`t8y2/dbx`** image from Docker Hub for immediate deployment without building from source
- Mount **`/app/data`** to a named volume to persist your SQLite database and uploaded files across container restarts
- Configure authentication by setting the **`DBX_PASSWORD`** environment variable
- Access the web interface on **port 4224** by default

## Frequently Asked Questions

### What architectures does the DBX Docker image support?

The official `t8y2/dbx` image is built as a multi-architecture image supporting both **amd64** and **arm64** platforms. The Dockerfile cross-compiles the Rust backend for the target architecture during the build process, ensuring native performance on both Intel/AMD and ARM-based systems like Raspberry Pi or Apple Silicon.

### How do I persist data when restarting the DBX container?

You must mount a volume to `/app/data` inside the container. This directory contains the SQLite database, configuration files, and uploaded user content. Using a named Docker volume (e.g., `dbx-data:/app/data`) ensures that your data remains intact even if you remove and recreate the container.

### Can I run DBX behind a reverse proxy with a sub-path?

Yes. Set the **`DBX_PUBLIC_BASE_PATH`** environment variable to specify the base path when DBX is served behind a reverse proxy. For example, setting `-e DBX_PUBLIC_BASE_PATH=/dbx` configures the application to expect requests at `http://your-domain.com/dbx` and adjusts internal routing accordingly.

### What is the difference between building from source and using the pre-built image?

The **pre-built image** (`t8y2/dbx`) from Docker Hub is ready to use and contains the compiled frontend and backend binaries. **Building from source** clones the repository and executes the multi-stage Dockerfile locally, which compiles the Vue 3 frontend with Node.js and cross-compiles the Rust `dbx-web` binary. Building from source is useful for development, customizing the code, or verifying the build process, while the pre-built image offers faster deployment for production use.