xCloud Docker Deploy
Adapt any docker-compose.yml to work with xCloud — a git-push Docker deployment platform.
How xCloud Works
CODEBLOCK0
xCloud never runs docker build. Images must be pre-built in a public registry. SSL, reverse proxy, and domain routing are handled by xCloud — your stack must not duplicate them.
Read references/xcloud-constraints.md for the full ruleset before making changes.
Phase 0 — Detect Project Type First
Before anything else, scan the project directory for these files:
Read DETECT.md for full detection rules. Quick routing:
| Found in project | Stack | Action |
|---|
| INLINECODE4 or INLINECODE5 | WordPress | Read INLINECODE6 |
| INLINECODE7 + INLINECODE8 |
Laravel | Read
references/xcloud-native-laravel.md |
|
package.json +
next.config.* | Next.js | Docker path → use
dockerfiles/nextjs.Dockerfile +
compose-templates/nextjs-postgres.yml |
|
package.json (no framework config) | Node.js | Read
references/xcloud-native-nodejs.md |
|
composer.json (no artisan) | PHP | Read
references/xcloud-native-php.md |
|
requirements.txt or
pyproject.toml | Python | Docker path → use
dockerfiles/python-fastapi.Dockerfile |
|
go.mod | Go | Docker path — generate Dockerfile manually |
|
docker-compose.yml exists | Existing Docker | Proceed to Step 1 below |
|
Dockerfile (no compose) | Build-from-source | Generate compose → Scenario A below |
See references/xcloud-deploy-paths.md for the Native vs Docker decision guide.
Step 1 — Detect Which Scenarios Apply
Inspect the provided docker-compose.yml:
| Signal | Scenario |
|---|
| INLINECODE26 or INLINECODE27 | A — Build-from-source |
| Caddy / Traefik / nginx-proxy service |
B — Proxy conflict |
| Multiple
ports: across services |
B — Multi-port |
|
./nginx.conf:/etc/nginx/... volume mount |
B — External config |
| Multiple services each with
build: |
C — Multi-service build |
|
image: some-public-image, single port | Already compatible — verify port + env vars |
A compose file can trigger multiple scenarios simultaneously (handle A first, then B).
Scenario A — Build-from-Source
Read references/scenario-build-source.md for full details.
What to do:
- 1. Remove
build: directive from compose - Replace
image: with INLINECODE35 - Generate
.github/workflows/docker-build.yml using assets/github-actions-build.yml template - Generate
.env.example from all ${VAR} references
Deliverables:
- - Modified INLINECODE40
- INLINECODE41
- INLINECODE42
- xCloud Deploy Steps (see Output Format)
Scenario B — Proxy Conflict / Multi-Port / External Config
Read references/scenario-proxy-conflict.md for full details.
What to do:
- 1. Remove Caddy/Traefik/nginx-proxy service entirely
- Remove SSL labels and multi-port
ports: from app services (replace with expose:) - Add
nginx-router service with inline config via configs: block - Expose single port (default:
3080) for xCloud to proxy
Deliverables:
- - Modified
docker-compose.yml with nginx-router + configs: block - INLINECODE52
- xCloud Deploy Steps
Scenario C — Multi-Service Build
Read references/scenario-multi-service-build.md for full details.
When multiple services have build: directives (separate frontend + backend + worker):
What to do:
- 1. For each service with
build:, create a separate GHCR image path - Generate a matrix GitHub Actions workflow that builds all images in parallel
- Update compose to use all GHCR image references
Deliverables:
- - Modified
docker-compose.yml (all build: removed) - INLINECODE58 (matrix strategy)
- INLINECODE59
Output Format
Always produce complete, copy-paste-ready output:
CODEBLOCK1
Rules
- - Never include
build: in the final compose — xCloud silently ignores it - Never expose database ports to host (remove
"5432:5432" — use expose: internally) - Never include Caddy, Traefik, nginx-proxy, or Let's Encrypt config
- Always preserve
environment:, volumes:, healthcheck:, worker/sidecar services - Always use
expose: (internal) not ports: (host) for services behind nginx-router - WebSockets? Add upgrade headers to nginx config (see proxy-conflict reference)
- INLINECODE68 inline syntax requires Docker Compose v2.23+ — use heredoc
command: alternative if uncertain
Examples
See examples/ for ready-made transformations:
- -
examples/rybbit-analytics.md — Caddy + multi-port app (Scenario B) - INLINECODE72 — build-from-source (Scenario A)
- INLINECODE73 — multi-service build (Scenario C)
xCloud Docker 部署
适配任意 docker-compose.yml 以兼容 xCloud——一个基于 git-push 的 Docker 部署平台。
xCloud 工作原理
git push → xCloud 执行: docker-compose pull && docker-compose up -d
xCloud 从不执行 docker build。 镜像必须预先构建并推送至公共镜像仓库。SSL、反向代理和域名路由由 xCloud 处理——你的堆栈不得重复实现这些功能。
在修改前请阅读 references/xcloud-constraints.md 了解完整规则集。
阶段 0 — 首先检测项目类型
在进行任何操作前，扫描项目目录查找以下文件：
阅读 DETECT.md 了解完整检测规则。快速路由：
| 项目中找到的文件 | 技术栈 | 操作 |
|---|
| wp-config.php 或 wp-content/ | WordPress | 阅读 references/xcloud-native-wordpress.md |
| composer.json + artisan |
Laravel | 阅读 references/xcloud-native-laravel.md |
| package.json + next.config.* | Next.js | Docker 路径 → 使用 dockerfiles/nextjs.Dockerfile + compose-templates/nextjs-postgres.yml |
| package.json（无框架配置） | Node.js | 阅读 references/xcloud-native-nodejs.md |
| composer.json（无 artisan） | PHP | 阅读 references/xcloud-native-php.md |
| requirements.txt 或 pyproject.toml | Python | Docker 路径 → 使用 dockerfiles/python-fastapi.Dockerfile |
| go.mod | Go | Docker 路径 — 手动生成 Dockerfile |
| docker-compose.yml 已存在 | 现有 Docker | 进入下方步骤 1 |
| Dockerfile（无 compose） | 源码构建 | 生成 compose → 下方场景 A |
阅读 references/xcloud-deploy-paths.md 了解原生部署与 Docker 部署的决策指南。
步骤 1 — 检测适用场景
检查提供的 docker-compose.yml：
| 信号 | 场景 |
|---|
| build: 或 build: context: . | A — 源码构建 |
| Caddy / Traefik / nginx-proxy 服务 |
B — 代理冲突 |
| 多个服务存在 ports: |
B — 多端口 |
| ./nginx.conf:/etc/nginx/... 卷挂载 |
B — 外部配置 |
| 多个服务各自包含 build: |
C — 多服务构建 |
| image: some-public-image，单端口 | 已兼容 — 验证端口和环境变量 |
一个 compose 文件可能同时触发多个场景（先处理 A，再处理 B）。
场景 A — 源码构建
阅读 references/scenario-build-source.md 了解完整详情。
操作步骤：
- 1. 从 compose 中移除 build: 指令
- 将 image: 替换为 ghcr.io/OWNER/REPO:latest
- 使用 assets/github-actions-build.yml 模板生成 .github/workflows/docker-build.yml
- 从所有 ${VAR} 引用生成 .env.example
交付物：
- - 修改后的 docker-compose.yml
- .github/workflows/docker-build.yml
- .env.example
- xCloud 部署步骤（参见输出格式）
场景 B — 代理冲突 / 多端口 / 外部配置
阅读 references/scenario-proxy-conflict.md 了解完整详情。
操作步骤：
- 1. 完全移除 Caddy/Traefik/nginx-proxy 服务
- 移除应用服务的 SSL 标签和多端口 ports:（替换为 expose:）
- 通过 configs: 块添加内联配置的 nginx-router 服务
- 暴露单端口（默认：3080）供 xCloud 代理
交付物：
- - 修改后的 docker-compose.yml，包含 nginx-router + configs: 块
- .env.example
- xCloud 部署步骤
场景 C — 多服务构建
阅读 references/scenario-multi-service-build.md 了解完整详情。
当多个服务包含 build: 指令时（独立的前端 + 后端 + 工作进程）：
操作步骤：
- 1. 为每个包含 build: 的服务创建独立的 GHCR 镜像路径
- 生成矩阵式 GitHub Actions 工作流，并行构建所有镜像
- 更新 compose 使用所有 GHCR 镜像引用
交付物：
- - 修改后的 docker-compose.yml（所有 build: 已移除）
- .github/workflows/docker-build.yml（矩阵策略）
- .env.example
输出格式
始终生成完整、可直接复制粘贴的输出：
修改后的 docker-compose.yml
[完整文件]
.github/workflows/docker-build.yml（仅场景 A/C）
[完整文件]
.env.example
[完整文件]
xCloud 部署步骤
- 1. 将仓库推送到 GitHub
2.（场景 A/C）等待 GitHub Actions 构建镜像 — 查看 Actions 标签页
- 3. 服务器 → 新建站点 → 自定义 Docker → 连接仓库
- 暴露端口：[PORT]
- 需添加的环境变量：[来自 .env.example 的列表]
- 部署
规则
- - 切勿在最终 compose 中包含 build:——xCloud 会静默忽略它
- 切勿将数据库端口暴露给宿主机（移除 5432:5432——内部使用 expose:）
- 切勿包含 Caddy、Traefik、nginx-proxy 或 Lets Encrypt 配置
- 始终保留 environment:、volumes:、healthcheck:、工作进程/边车服务
- 始终对 nginx-router 后端的服务使用 expose:（内部）而非 ports:（宿主机）
- WebSocket？ 在 nginx 配置中添加升级头（参见代理冲突参考文档）
- configs.content: 内联语法需要 Docker Compose v2.23+——如果不确定，使用 heredoc command: 替代方案
示例
参见 examples/ 获取现成的转换示例：
- - examples/rybbit-analytics.md — Caddy + 多端口应用（场景 B）
- examples/custom-app-dockerfile.md — 源码构建（场景 A）
- examples/fullstack-monorepo.md — 多服务构建（场景 C）
