Deploy with Dokploy

This guide describes one production deployment path: build Duobox Server from a Dockerfile and let Dokploy manage the container lifecycle, domain, HTTPS, logs, and restarts.

To declare the build, configuration, and persistent storage in one Compose file, see Deploy with Dokploy Compose.

Duobox Server stores one SQLite database and local bare Git repositories. Keep the replica count at 1 and persist the entire /data directory because one data directory must be owned by exactly one Server instance.

Requirements

Prepare the following:

• a Dokploy instance;
• a public domain such as spaces.example.com;
• a Downcity Federation URL, Bureau Token, and City ID;
• a Git repository for the Dockerfile.

1. Create the Dockerfile

Add this Dockerfile at the root of the deployment repository:

FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends git curl ca-certificates \
    && npm install -g @duobox/cli@latest \
    && rm -rf /var/lib/apt/lists/*

RUN mkdir -p /data && chown node:node /data

ENV DUOBOX_REMOTE_HOST=0.0.0.0
ENV DUOBOX_REMOTE_PORT=4178
ENV DUOBOX_REMOTE_DATA=/data

USER node
VOLUME ["/data"]
EXPOSE 4178

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -fsS http://127.0.0.1:4178/v1/info || exit 1

CMD ["duobox", "server", "start", "--foreground"]

The container must use server start --foreground. Duobox remains the foreground main process while Dokploy owns shutdown, restarts, and logs.

Pin the CLI version in production. Upgrade by changing the version in the Dockerfile and rebuilding instead of installing dependencies every time the container starts.

2. Create the Application

Create an Application in Dokploy:

1. connect the Git repository containing the Dockerfile;
2. select Dockerfile as the build type;
3. set the container port to 4178;
4. keep the replica count at 1;
5. mount a persistent volume at /data;
6. route spaces.example.com to the Application and enable HTTPS;
7. set the health check path to /v1/info.

Do not configure /data as ephemeral storage. The same volume must remain attached after container rebuilds.

3. Configure environment variables

Add these values to the Application environment:

DOWNCITY_FEDERATION_URL=https://base.downcity.ai
DOWNCITY_BUREAU_TOKEN=replace-with-your-bureau-token
DOWNCITY_CITY_ID=duobox

DUOBOX_REMOTE_HOST=0.0.0.0
DUOBOX_REMOTE_PORT=4178
DUOBOX_REMOTE_URL=https://spaces.example.com
DUOBOX_REMOTE_DATA=/data

Important details:

• DUOBOX_REMOTE_HOST must be 0.0.0.0 so Dokploy can reach the container port;
• DUOBOX_REMOTE_URL must be the public HTTPS origin, not localhost, a container name, or an internal port;
• keep DOWNCITY_BUREAU_TOKEN in Dokploy as a secret and never commit it to Git.

4. Deploy and verify

Start the deployment and wait for the health check to pass. Verify the public endpoint from outside Dokploy:

curl https://spaces.example.com/v1/info

A successful request returns the Duobox Server information. If the health check fails, inspect the Application Logs and verify the port, environment variables, and Federation connectivity.

5. Link Organizations and manage access

Run administrative commands in the Dokploy Application Terminal:

duobox login
duobox server organization list
duobox server organization link <organization-id-or-key>
duobox server organization access set <organization-id> <user-id> --role editor

The active Federation user must be allowed to update the Organization Server URL. Membership governance remains in Federation.

Data, backups, and upgrades

/data contains both:

• server.db for Spaces, project ACL, and audit records;
• repositories/ for all Remote Space Git data.

Back up the entire volume as one unit. Backing up only the database or only the repositories can produce inconsistent data.

To upgrade:

1. back up the /data volume;
2. change the pinned @duobox/cli version in the Dockerfile;
3. redeploy from Dokploy;
4. keep the existing /data volume attached;
5. verify /v1/info and inspect the logs.

Common mistakes

• setting replicas above 1, which makes multiple processes share SQLite and repositories;
• failing to persist /data, which loses Spaces, project ACL, and Git history after a rebuild;
• listening on 127.0.0.1, which prevents Dokploy from reaching the container port;
• using an internal address as DUOBOX_REMOTE_URL, which makes Organization Space and Git endpoints unreachable;
• buffering Git requests or enforcing a proxy body limit below the Server limit;
• deploying where the Federation cannot be reached from the container.