使用 Dokploy Compose 部署

直接在 Dokploy UI 中创建 Compose 服务，部署并持久化 Vibecape Server。

本教程通过 Dokploy UI 创建 Compose 服务并部署 Vibecape Server。

Vibecape Server 会把 Space repositories 创建在 /data/repositories/ 中，并随 /data Volume 一起持久化。

Vibecape Server 同时使用 SQLite，因此 Compose service 只能运行一个实例。不要扩容，也不要让多个 Server 容器挂载同一个数据卷。

1. 创建 Compose 服务

进入 Dokploy：

新建或选择一个 Project；
点击创建 Service；
选择 Compose；
输入服务名称，例如 vibecape；
选择直接编辑 Compose 配置的方式；
保存 Compose 服务，进入配置页面。

2. 粘贴 Compose 配置

在 Dokploy 的 Compose 编辑器中粘贴：

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 在 Compose 配置中声明 Vibecape 镜像的构建过程。

关键点：

start --foreground 让 Vibecape 成为容器主进程，由 Dokploy 管理停止、重启和日志；
vibecape_data 持久化数据库和全部 Space repositories；
expose 只暴露容器端口，不占用宿主机固定端口；
不设置 container_name，避免重新部署时命名冲突；
不设置多副本，避免多个进程同时操作 SQLite 和 repositories。

3. 配置环境变量

在 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 是用户实际访问的公开 HTTPS 地址；
不要填写 service 名、容器地址、localhost 或内部端口；
DOWNCITY_BUREAU_TOKEN 只保存在 Dokploy Environment 中，不要直接写入 Compose 配置。

4. 配置域名

在 Compose service 的 Domains 中添加：

Domain：spaces.example.com；
Service：vibecape；
Container Port：4178；
Path：/；
HTTPS：启用。

Domain 必须与 VIBECAPE_REMOTE_URL 完全一致。修改域名后，需要同步修改环境变量并重新部署。

5. 部署与验证

点击 Deploy。Dokploy 会根据内联 Dockerfile 构建镜像、创建 vibecape_data Volume，并启动 Server。

部署完成后验证：

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

如果失败，依次检查：

Deploy Logs 中镜像是否构建成功；
Application Logs 中 Server 是否监听 0.0.0.0:4178；
环境变量是否完整；
Domain 是否指向 vibecape:4178；
容器是否可以访问配置的 Federation。

6. 创建 Group 和 Space

部署完成后，在 Dokploy 中打开 vibecape service 的 Terminal，创建 Group：

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

用户加入 Group 后，由 Owner 在 Vibecape App 中创建 Space。Vibecape Server 会自动在 /data/repositories/ 中创建对应的 bare Git repository。

加入申请仍在 Terminal 中审批：

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

备份与升级

vibecape_data Volume 同时保存：

server.db：Group、成员、Space 和权限；
repositories/：全部 Remote Space Git 数据。

必须整体备份 Volume，不能只备份其中一部分。

升级时：

备份 vibecape_data；
在 Compose 编辑器中重新构建最新的 @vibecape/cli；
保存并重新部署；
确认仍然挂载原来的 vibecape_data Volume；
检查日志和 /v1/info。

不要随意修改 Compose service 名或 Volume 名，否则可能创建新的空 Volume，看起来像数据丢失。