Deploy with Dokploy

This guide describes one production deployment path: build Vibecape 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.

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

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

ENV VIBECAPE_REMOTE_HOST=0.0.0.0
ENV VIBECAPE_REMOTE_PORT=4178
ENV VIBECAPE_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 ["vibecape", "server", "start", "--foreground"]

The container must use server start --foreground. Vibecape 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=vibecape

VIBECAPE_REMOTE_HOST=0.0.0.0
VIBECAPE_REMOTE_PORT=4178
VIBECAPE_REMOTE_URL=https://spaces.example.com
VIBECAPE_REMOTE_DATA=/data

Important details:

• VIBECAPE_REMOTE_HOST must be 0.0.0.0 so Dokploy can reach the container port;
• VIBECAPE_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 Vibecape Server information. If the health check fails, inspect the Application Logs and verify the port, environment variables, and Federation connectivity.

5. Administer Groups

Run administrative commands in the Dokploy Application Terminal:

vibecape server group list
vibecape server group create \
  --name "Research Team" \
  --owner "federation-user-id"
vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> --role editor

Prefer an explicit --owner inside the container so administration does not depend on a CLI account stored in the container filesystem.

Data, backups, and upgrades

/data contains both:

• server.db for Groups, members, Spaces, and permissions;
• 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 @vibecape/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 Groups, Spaces, 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 VIBECAPE_REMOTE_URL, which produces unusable Group and Git URLs;
• buffering Git requests or enforcing a proxy body limit below the Server limit;
• deploying where the Federation cannot be reached from the container.