Deploy with Dokploy Compose

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

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

Vibecape 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, vibecape;
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:
  vibecape:
    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 @vibecape/cli@latest \
            && rm -rf /var/lib/apt/lists/*

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

        USER node
        EXPOSE 4178

        CMD ["vibecape", "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}
      VIBECAPE_REMOTE_HOST: 0.0.0.0
      VIBECAPE_REMOTE_PORT: "4178"
      VIBECAPE_REMOTE_URL: ${VIBECAPE_REMOTE_URL:?required}
      VIBECAPE_REMOTE_DATA: /data
    expose:
      - "4178"
    volumes:
      - vibecape_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:
  vibecape_data:

dockerfile_inline declares the Vibecape image build inside the Compose configuration.

Important details:

• start --foreground keeps Vibecape as the main process while Dokploy owns shutdown, restarts, and logs;
• vibecape_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=vibecape
VIBECAPE_REMOTE_URL=https://spaces.example.com

VIBECAPE_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: vibecape;
• Container Port: 4178;
• Path: /;
• HTTPS: enabled.

The domain must match VIBECAPE_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 vibecape_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 vibecape:4178;
5. the container can reach the configured Federation.

6. Create Groups and Spaces

After deployment, open the Terminal for the vibecape service and create a Group:

vibecape server group list
vibecape server group create \
  --name "Research Team" \
  --owner "federation-user-id"

After users join the Group, its Owner creates Spaces in the Vibecape App. Vibecape Server automatically creates each bare Git repository under /data/repositories/.

Approve join requests from the Terminal:

vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> --role editor

Back up and upgrade

The vibecape_data volume contains both:

• server.db for Groups, members, Spaces, and permissions;
• repositories/ for all Remote Space Git data.

Back up the whole volume as one unit.

To upgrade:

1. back up vibecape_data;
2. rebuild the latest @vibecape/cli from the Compose editor;
3. save and redeploy;
4. confirm the existing vibecape_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.