Deploy with Dokploy Compose

This guide creates a Compose service in the Dokploy UI and deploys Duobox Server from its configuration.

Duobox Server creates Space repositories under /data/repositories/, and the /data volume persists them.

Duobox Server also uses SQLite, so run exactly one Compose service instance. Do not scale it or mount the same data volume into multiple Server containers.

1. Create the Compose service

In Dokploy:

1. create or select a Project;
2. create a new Service;
3. select Compose;
4. name it, for example, duobox;
5. select the option to edit the Compose configuration directly;
6. save the Compose service and open its configuration page.

2. Paste the Compose configuration

Paste this into the Dokploy Compose editor:

services:
  duobox:
    build:
      context: .
      dockerfile_inline: |
        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

        USER node
        EXPOSE 4178

        CMD ["duobox", "server", "start", "--foreground"]
    init: true
    environment:
      DOWNCITY_FEDERATION_URL: ${DOWNCITY_FEDERATION_URL:?required}
      DOWNCITY_BUREAU_TOKEN: ${DOWNCITY_BUREAU_TOKEN:?required}
      DOWNCITY_CITY_ID: ${DOWNCITY_CITY_ID:?required}
      DUOBOX_REMOTE_HOST: 0.0.0.0
      DUOBOX_REMOTE_PORT: "4178"
      DUOBOX_REMOTE_URL: ${DUOBOX_REMOTE_URL:?required}
      DUOBOX_REMOTE_DATA: /data
    expose:
      - "4178"
    volumes:
      - duobox_data:/data
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:4178/v1/info"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    stop_grace_period: 30s

volumes:
  duobox_data:

dockerfile_inline declares the Duobox image build inside the Compose configuration.

Important details:

• start --foreground keeps Duobox as the main process while Dokploy owns shutdown, restarts, and logs;
• duobox_data persists the database and every Space repository;
• expose makes the container port available without binding a fixed host port;
• omitting container_name prevents naming conflicts during redeployment;
• keeping one instance prevents concurrent access to SQLite and repositories.

3. Configure environment variables

Add these values to the Compose service environment:

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

DUOBOX_REMOTE_URL must be the public HTTPS origin used by App users. Do not use a service name, container address, localhost, or an internal port.

Keep DOWNCITY_BUREAU_TOKEN in the Dokploy environment. Do not place the actual token directly in the Compose configuration.

4. Configure the domain

Add a domain to the Compose service:

• Domain: spaces.example.com;
• Service: duobox;
• Container Port: 4178;
• Path: /;
• HTTPS: enabled.

The domain must match DUOBOX_REMOTE_URL. Update the environment variable and redeploy whenever the domain changes.

5. Deploy and verify

Click Deploy. Dokploy builds the inline Dockerfile, creates the duobox_data volume, and starts the Server.

Verify the public endpoint:

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

If it fails, check these items in order:

1. the image completed in Deploy Logs;
2. Application Logs show the Server listening on 0.0.0.0:4178;
3. all environment variables are present;
4. the domain targets duobox:4178;
5. the container can reach the configured Federation.

6. Link Organizations and create Spaces

After deployment, open the Terminal for the duobox service and link an Organization:

duobox login
duobox server organization list
duobox server organization link <organization-id-or-key>

Users with manager access create Spaces in the Duobox App. Duobox Server automatically creates each bare Git repository under /data/repositories/.

Grant a Federation Member project push access from the Terminal:

duobox server organization access set <organization-id> <user-id> --role editor

Back up and upgrade

The duobox_data volume contains both:

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

Back up the whole volume as one unit.

To upgrade:

1. back up duobox_data;
2. rebuild the latest @duobox/cli from the Compose editor;
3. save and redeploy;
4. confirm the existing duobox_data volume remains attached;
5. inspect the logs and verify /v1/info.

Do not casually rename the Compose service or volume. Compose may create a new empty volume, making existing data appear to be lost.