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

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:

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 file. This declarative configuration defines the service, maps port 4224, and creates a named volume dbx-data mounted to /app/data for state persistence:

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:

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

Method 3: Building from Source

To build the image locally from the repository:

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 (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.

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