# How to Set Up DBX Multi-Arch Deployment: Cross-Platform Container Builds

> Learn how to set up DBX multi-arch deployment for cross-platform container builds using Docker BuildKit. Effortlessly deploy on amd64 and arm64.

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

---

**DBX supports native multi-architecture deployment on both amd64 and arm64 platforms using Docker BuildKit and a multi-stage Dockerfile that cross-compiles the Rust backend and Vue 3 frontend for the target architecture.**

The t8y2/dbx repository ships database management tools that require seamless operation across heterogeneous infrastructure. Setting up a DBX multi-arch deployment ensures your containers run natively on Intel/AMD and ARM64 servers without emulation overhead, leveraging the same image tag regardless of underlying hardware.

## Prerequisites for Multi-Architecture Builds

Before building, ensure your environment meets these requirements:

- **Docker 20.10** or newer with **BuildKit** enabled (`export DOCKER_BUILDKIT=1`)
- **docker buildx** (included in modern Docker Desktop and Engine installations)
- Access to a container registry (Docker Hub, GHCR, or private registry) for pushing multi-arch manifests

## Understanding the Multi-Stage Dockerfile

The `deploy/Dockerfile` in the t8y2/dbx repository implements a three-stage build process that separates frontend compilation from backend cross-compilation. This design prevents emulation penalties by building the Vue 3 UI on the host platform while cross-compiling the Rust binary for the target architecture.

### Frontend Stage (Build Platform)

The build begins with a frontend stage that uses `--platform=$BUILDPLATFORM` to compile the Vue 3 UI using the host's native architecture. This stage executes quickly because it does not target the final runtime architecture, leveraging the host's full CPU performance for Node.js and Vite operations.

### Backend Cross-Compilation Stage

The backend stage installs the cross-compilation toolchain (`gcc-aarch64-linux-gnu`) and configures Rust targets for both architectures. According to the source code in `deploy/Dockerfile` (lines 15-25), the build adds the `x86_64-unknown-linux-gnu` and `aarch64-unknown-linux-gnu` targets to the Rust toolchain.

The `TARGETARCH` build argument (lines 40-48) drives conditional logic that selects the appropriate Rust target and system library directory (`lib_arch`). When `TARGETARCH` equals `arm64`, the build uses the `aarch64-unknown-linux-gnu` target; for `amd64`, it uses `x86_64-unknown-linux-gnu`. After a dummy compilation step to cache dependencies (lines 59-70), the real source is copied and compiled for the selected architecture.

### Final Runtime Stage

The final stage assembles a minimal Debian bookworm-slim image (lines 72-87) that copies only the compiled `dbx-web` binary and static frontend assets. This produces a small, secure image without build tooling that runs natively on the target platform.

## Building the Multi-Arch Image

Create a dedicated Buildx builder instance to handle multi-platform compilation:

```bash
docker buildx create --use --name dbx-builder
docker buildx inspect --bootstrap

```

Build and push the image for both amd64 and arm64 architectures simultaneously:

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t t8y2/dbx:latest \
  -f deploy/Dockerfile \
  --push .

```

The `--platform` flag instructs BuildKit to invoke the Dockerfile twice, once with `TARGETARCH=amd64` and once with `TARGETARCH=arm64`. The Dockerfile's conditional logic automatically selects the correct Rust target and library paths for each invocation.

## Running DBX Containers

### Single Container Deployment

Run the container directly while mounting a volume for persistent data storage:

```bash
docker run -d \
  --name dbx \
  -p 4224:4224 \
  -v dbx-data:/app/data \
  t8y2/dbx:latest

```

The container exposes the DBX web UI on **http://localhost:4224**. The `dbx-data` volume stores the SQLite-based connection catalog, ensuring data persists across container restarts.

### Docker Compose Deployment

The repository provides a ready-to-use Compose definition in [`deploy/docker-compose.yml`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) that pulls the pre-built multi-arch image from Docker Hub:

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

```

This configuration forwards port 4224, mounts a named volume for the data directory, and configures automatic restart policies unless stopped manually.

## Optional: Reverse Proxy Sub-Path Configuration

If serving DBX behind a reverse proxy at a sub-path (e.g., `https://example.com/dbx`), set the environment variable `DBX_PUBLIC_BASE_PATH=/dbx` and configure your proxy to strip the prefix before forwarding requests to the container. The repository's [`apps/desktop/vite.config.ts`](https://github.com/t8y2/dbx/blob/main/apps/desktop/vite.config.ts) configures the static asset base path to support this deployment pattern.

## Summary

- **DBX multi-arch deployment** requires Docker BuildKit and a multi-stage Dockerfile that separates build-platform frontend compilation from target-platform backend compilation.
- The `deploy/Dockerfile` uses `TARGETARCH` to conditionally select between `x86_64-unknown-linux-gnu` and `aarch64-unknown-linux-gnu` Rust targets, avoiding emulation overhead.
- Pre-built images are available as `t8y2/dbx:latest` on Docker Hub, supporting both amd64 and arm64 architectures under a single manifest.
- Data persistence requires mounting a volume to `/app/data` to store the SQLite connection catalog.
- The [`deploy/docker-compose.yml`](https://github.com/t8y2/dbx/blob/main/deploy/docker-compose.yml) file provides a production-ready orchestration template with proper port mapping and volume configuration.

## Frequently Asked Questions

### Does DBX support ARM64 processors like Apple Silicon or AWS Graviton?

Yes. The t8y2/dbx repository explicitly supports arm64 (aarch64) architecture alongside amd64 (x86_64). The multi-arch Docker image runs natively on Apple Silicon Macs, Raspberry Pi devices, and AWS Graviton instances without requiring Rosetta 2 or QEMU emulation.

### Why do I need docker buildx for multi-arch deployment?

Standard Docker builds only target the host's native architecture. The `docker buildx` command creates a builder instance capable of cross-compilation and manifest list generation, allowing a single image tag to contain separate binaries for amd64 and arm64. BuildKit also enables the `--platform` flag that drives the conditional logic in `deploy/Dockerfile`.

### Where is data stored in a DBX container?

DBX stores its SQLite-based connection catalog in `/app/data` inside the container. You must mount a persistent volume (e.g., `-v dbx-data:/app/data`) to ensure your database connections and settings survive container restarts or image updates.

### Can I build the multi-arch image without pushing to a registry?

No. When building for multiple platforms simultaneously, Docker requires a registry to store the manifest list that combines the architecture-specific layers. You can push to a local registry (localhost:5000) or Docker Hub. Single-platform builds can be loaded locally using `--load`, but multi-platform builds require `--push`.