coolify-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coolify Orchestrator

A stack-aware, MCP-optional skill that orchestrates your Coolify infrastructure.

一款支持栈感知、可选MCP的技能，用于编排你的Coolify基础设施。

First: Determine Operating Mode

第一步：确定运行模式

Understand which mode you are operating in at the beginning of each session:

MCP_AVAILABLE = Can coolify-mcp MCP tools be called?
  Yes → MCP mode: use tools directly (references/api.md is unnecessary)
  No → API mode: use Coolify REST API via curl/bash (read references/api.md)

Even in MCP mode, the decision trees and playbooks in this SKILL.md are valid — MCP is just the transport layer.

Find or ask for environment variables:

COOLIFY_BASE_URL

— e.g.

https://coolify.example.com

```
COOLIFY_ACCESS_TOKEN
```
— Coolify Settings → API Tokens

If these aren't in the env, ask the user. Do not ask for the second time — save it for the duration of the conversation.

在每次会话开始时，先明确你所处的运行模式：

MCP_AVAILABLE = 是否可以调用coolify-mcp MCP工具？
  是 → MCP模式：直接使用工具（无需参考references/api.md）
  否 → API模式：通过curl/bash调用Coolify REST API（需阅读references/api.md）

即使在MCP模式下，本SKILL.md中的决策树和操作手册依然有效——MCP只是传输层。

查找或询问环境变量：

COOLIFY_BASE_URL

— 示例：

https://coolify.example.com

```
COOLIFY_ACCESS_TOKEN
```
— Coolify设置 → API令牌

如果这些变量不在环境中，请询问用户。无需重复询问——在会话期间保存即可。

Scenario Detection → Playbook Routing

场景检测 → 操作手册路由

Match the user's request with this tree:

Is it about "deploy" or "build"?
  + Turborepo / monorepo / package error → [TURBO-DEPLOY]
  + Normal app deploy → [DEPLOY-VERIFY]

Is it about "down" / "unhealthy" / "error"?
  + Container/file issue (htaccess, config, .env) → [CONTAINER-EXEC]
  + API/service issue → [DEPLOY-VERIFY] (diagnose flow)

Is it about "new" / "provisioning" / "tenant"?
  → [PROVISIONING]

Is it about "env var" / "environment" / "secret"?
  → [MULTI-TENANT-ENV]

Is SSH / container terminal / exec requested?
  → [CONTAINER-EXEC]

Read the relevant reference file for each playbook.

将用户请求与以下决策树匹配：

是否涉及“deploy”（部署）或“build”（构建）？
  + Turborepo / 单体仓库 / 包错误 → [TURBO-DEPLOY]
  + 常规应用部署 → [DEPLOY-VERIFY]

是否涉及“down”（停机）/“unhealthy”（不健康）/“error”（错误）？
  + 容器/文件问题（htaccess、配置、.env） → [CONTAINER-EXEC]
  + API/服务问题 → [DEPLOY-VERIFY]（诊断流程）

是否涉及“new”（新建）/“provisioning”（配置）/“tenant”（租户）？
  → [PROVISIONING]

是否涉及“env var”（环境变量）/“environment”（环境）/“secret”（密钥）？
  → [MULTI-TENANT-ENV]

是否请求SSH / 容器终端 / exec命令？
  → [CONTAINER-EXEC]

针对每个操作手册阅读对应的参考文件。

[TURBO-DEPLOY] Turborepo + Coolify Deploy Playbook

[TURBO-DEPLOY] Turborepo + Coolify 部署操作手册

Detail:

references/turborepo-deploy.md

When to trigger: When a Turborepo monorepo is deployed on Coolify and the following errors are seen:

```
Cannot find module '@myapp/shared'
```
```
tsconfig.json
```
cannot be found
Shared package acts as if it hasn't been built
TypeScript error in the middle of Docker build

Quick diagnosis:

Check the
```
COPY
```
order in the Dockerfile — shared packages must be built first
Is there a dependency pipeline in
```
turbo.json
```
?
Is Coolify's Docker build context correct? (monorepo root or subdirectory?)

bash

undefined

详情：

references/turborepo-deploy.md

**触发时机：**当Turborepo单体仓库在Coolify上部署，且出现以下错误时：

```
Cannot find module '@myapp/shared'
```
无法找到
```
tsconfig.json
```
共享包似乎未被构建
Docker构建过程中出现TypeScript错误

快速诊断：

检查Dockerfile中的
```
COPY
```
顺序——共享包必须先构建
```
turbo.json
```
中是否有依赖流水线？
Coolify的Docker构建上下文是否正确？（单体仓库根目录还是子目录？）

bash

undefined

API mode — fetch build logs

API模式 — 获取构建日志

curl -s -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
"$COOLIFY_BASE_URL/api/v1/applications/{uuid}/logs" | tail -100


In MCP mode: Use `application_logs(uuid)` → `deployment(action: list_for_app)` to find the last deploy.

When you identify the problem, read `references/turborepo-deploy.md` — fix patterns are there.

---

curl -s -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
"$COOLIFY_BASE_URL/api/v1/applications/{uuid}/logs" | tail -100


在MCP模式下：使用`application_logs(uuid)` → `deployment(action: list_for_app)`查找最近一次部署记录。

确定问题后，阅读`references/turborepo-deploy.md`——其中包含修复方案。

---

[DEPLOY-VERIFY] Deploy → Automatically Verify Loop

[DEPLOY-VERIFY] 部署 → 自动验证循环

Detail:

references/deploy-verify.md

Objective: Trigger deploy, verify healthy operation, diagnose if there is an error.

Steps:

1. Trigger deploy
   MCP: deploy(uuid, force_rebuild?)
   API: POST /api/v1/applications/{uuid}/start

2. Monitor deploy status (max 3 minutes, 10s intervals)
   MCP: deployment(action: get, uuid: deploy_uuid)
   API: GET /api/v1/deployments/{uuid}
   Expected: "finished" — if "failed", fetch logs

3. Application health check
   MCP: diagnose_app(uuid or domain)
   API: GET /api/v1/applications/{uuid} → status: "running:healthy"?

4. HTTP probe (For Hono/Next.js)
   curl -sf https://{domain}/health || curl -sf https://{domain}/api/health
   Successful if it returns 200.

5. If failed → analyze logs and find the root cause

Bun/Hono health check endpoint assumption:

GET /health → { status: "ok", uptime: X }
GET /api/health → 200 OK

If this endpoint does not exist, ask the user to add it.

Deploy monitoring loop (bash):

bash

for i in $(seq 1 18); do
  STATUS=$(curl -s -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN" \
    "$COOLIFY_BASE_URL/api/v1/deployments/$DEPLOY_UUID" | jq -r '.status')
  echo "[$i] $STATUS"
  [ "$STATUS" = "finished" ] && break
  [ "$STATUS" = "failed" ] && echo "ERROR: Deploy failed" && break
  sleep 10
done

详情：

references/deploy-verify.md

**目标：**触发部署，验证运行状态是否健康，若出现错误则进行诊断。

步骤：

1. 触发部署
   MCP：deploy(uuid, force_rebuild?)
   API：POST /api/v1/applications/{uuid}/start

2. 监控部署状态（最多3分钟，间隔10秒）
   MCP：deployment(action: get, uuid: deploy_uuid)
   API：GET /api/v1/deployments/{uuid}
   预期状态："finished" — 若为"failed"，则获取日志

3. 应用健康检查
   MCP：diagnose_app(uuid or domain)
   API：GET /api/v1/applications/{uuid} → 状态是否为"running:healthy"？

4. HTTP探测（针对Hono/Next.js）
   curl -sf https://{domain}/health || curl -sf https://{domain}/api/health
   返回200则视为成功。

5. 若失败 → 分析日志并找出根本原因

Bun/Hono健康检查端点假设：

GET /health → { status: "ok", uptime: X }
GET /api/health → 200 OK

如果该端点不存在，请要求用户添加。

部署监控循环（bash）：

bash

for i in $(seq 1 18); do
  STATUS=$(curl -s -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN" \
    "$COOLIFY_BASE_URL/api/v1/deployments/$DEPLOY_UUID" | jq -r '.status')
  echo "[$i] $STATUS"
  [ "$STATUS" = "finished" ] && break
  [ "$STATUS" = "failed" ] && echo "ERROR: Deploy failed" && break
  sleep 10
done

[PROVISIONING] New Service Provisioning

[PROVISIONING] 新服务配置

Detail:

references/provisioning.md

Objective: Set up all services from scratch for a tenant/project.

Standard order — strictly follow this order:

1. Create project (or find existing project)
2. Create environment (staging / production)
3. Create database and obtain connection credentials
4. Create application (source: Docker image / GitHub repo)
5. Set env vars (including DB_URL)
6. Deploy
7. Run [DEPLOY-VERIFY] loop

Select stack template (ask user if not specified):

Stack	Template
Bun + Hono + PostgreSQL	`references/provisioning.md#bun-hono-pg`
Next.js + PostgreSQL + Redis	`references/provisioning.md#nextjs-pg-redis`
PostgreSQL only	`references/provisioning.md#db-only`

Pre-provisioning data collection from user:

Project/tenant name
Target environment (staging/production)
Source (Docker image tag or GitHub repo + branch)
Domain (for Traefik)

详情：

references/provisioning.md

**目标：**为租户/项目从头搭建所有服务。

标准顺序——严格遵循：

1. 创建项目（或查找现有项目）
2. 创建环境（ staging / production）
3. 创建数据库并获取连接凭证
4. 创建应用（来源：Docker镜像 / GitHub仓库）
5. 设置环境变量（包括DB_URL）
6. 部署
7. 运行[DEPLOY-VERIFY]循环

选择栈模板（若未指定则询问用户）：

栈	模板
Bun + Hono + PostgreSQL	`references/provisioning.md#bun-hono-pg`
Next.js + PostgreSQL + Redis	`references/provisioning.md#nextjs-pg-redis`
仅PostgreSQL	`references/provisioning.md#db-only`

配置前向用户收集的数据：

项目/租户名称
目标环境（staging/production）
来源（Docker镜像标签或GitHub仓库 + 分支）
域名（用于Traefik）

[MULTI-TENANT-ENV] Multi-Tenant Env Var Management

[MULTI-TENANT-ENV] 多租户环境变量管理

Detail:

references/multi-tenant-env.md

Objective: Manage env vars securely and isolatedly for multiple apps/tenants.

Basic rules:

Each tenant's env vars should go only to their app — strictly no cross-contamination
You must always restart after changes
Do not show secrets in the log — apply masking

Update env var for single application:

bash

undefined

详情：

references/multi-tenant-env.md

**目标：**为多个应用/租户安全、隔离地管理环境变量。

基本规则：

每个租户的环境变量应仅作用于其自身应用——严格禁止交叉污染
修改后必须重启服务
日志中不得显示密钥——需进行掩码处理

更新单个应用的环境变量：

bash

undefined

List

列出变量

curl -s -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
"$COOLIFY_BASE_URL/api/v1/applications/$APP_UUID/envs"

Add/update

添加/更新

curl -s -X POST -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
-H "Content-Type: application/json"
-d '{"key":"DATABASE_URL","value":"...","is_multiline":false}'
"$COOLIFY_BASE_URL/api/v1/applications/$APP_UUID/envs"


In MCP mode: `env_vars(resource: application, action: create|update, uuid, key, value)`

**Bulk update (multiple applications):**
If MCP is present: `bulk_env_update(app_uuids: [...], key, value)` — write to all apps with a single command.
In API mode: run the `references/multi-tenant-env.md#bulk-script` script.

**Verify: isolation check**
List the env vars of each app, ensure that `DATABASE_URL` values are different.

---


在MCP模式下：`env_vars(resource: application, action: create|update, uuid, key, value)`

**批量更新（多个应用）：**
若存在MCP：`bulk_env_update(app_uuids: [...], key, value)` — 一条命令即可写入所有应用。
在API模式下：运行`references/multi-tenant-env.md#bulk-script`脚本。

**验证：隔离性检查**
列出每个应用的环境变量，确保`DATABASE_URL`的值各不相同。

---

[CONTAINER-EXEC] Container Exec / SSH Fallback

[CONTAINER-EXEC] 容器执行 / SSH fallback

Detail:

references/container-exec.md

When to use:

When API is insufficient (file editing, config patch, log file reading)
When
```
.env
```
/ config file needs to be edited inside the container
In-container debug (node_modules, bun cache, etc.)

Access strategy (try in order):

1. Coolify Dashboard → Service → Terminal (web UI) — easiest
2. SSH → server → docker exec — if shell access is available
3. Coolify API exec endpoint (if available) — programmatic

SSH + docker exec:

bash

undefined

详情：

references/container-exec.md

使用场景：

当API功能不足时（文件编辑、配置补丁、日志文件读取）
需要在容器内编辑
```
.env
```
/ 配置文件时
容器内调试（node_modules、bun缓存等）

访问策略（按顺序尝试）：

1. Coolify控制台 → 服务 → 终端（Web UI）——最简单
2. SSH → 服务器 → docker exec ——若有shell访问权限
3. Coolify API执行端点（若可用）——程序化操作

SSH + docker exec：

bash

undefined

Connect to server

连接到服务器

ssh user@coolify-server

Find container name

查找容器名称

docker ps | grep <service-name>

Enter container

进入容器

docker exec -it <container-name> sh

or if bash exists:

若存在bash则使用：

docker exec -it <container-name> bash


**File path assumptions in Coolify:**

| Service | File path |
|--------|------------|
| Bun/Node app | `/app/` or `/usr/src/app/` |
| Next.js | `/app/` |
| PostgreSQL data | `/var/lib/postgresql/data/` |

After in-container operations are completed, **always** restart the service:
```bash

docker exec -it <container-name> bash


**Coolify中的文件路径假设：**

| 服务 | 文件路径 |
|--------|------------|
| Bun/Node应用 | `/app/` 或 `/usr/src/app/` |
| Next.js | `/app/` |
| PostgreSQL数据 | `/var/lib/postgresql/data/` |

容器内操作完成后，**必须**重启服务：
```bash

API mode

API模式

curl -X POST -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
"$COOLIFY_BASE_URL/api/v1/applications/$APP_UUID/restart"

---

curl -X POST -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN"
"$COOLIFY_BASE_URL/api/v1/applications/$APP_UUID/restart"

---

General Principles

通用原则

Token efficiency: First use summary endpoints, if detail is needed go to single source.

Order in case of error:

Fetch logs (last 200 lines is enough)
Check status
Look at
```
references/
```
files for known error patterns
Ask user one clarifying question — not multiple

Security:

Never show API token in log or output
Mask env var values:
```
DATABASE_URL=postgres://***
```
Obtain user approval prior to destructive operations (stop_all, delete)

Coolify API base pattern:

bash

curl -s \
  -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "$COOLIFY_BASE_URL/api/v1/{endpoint}"

**令牌效率：**优先使用汇总端点，若需要详情再访问单一数据源。

错误处理顺序：

获取日志（最后200行即可）
检查状态
查看
```
references/
```
文件中的已知错误模式
向用户提出一个澄清问题——不要多个

安全：

日志或输出中绝不能显示API令牌
环境变量值掩码处理：
```
DATABASE_URL=postgres://***
```
执行破坏性操作（stop_all、delete）前需获得用户批准

Coolify API基础模式：

bash

curl -s \
  -H "Authorization: Bearer $COOLIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  "$COOLIFY_BASE_URL/api/v1/{endpoint}"

Reference Files

参考文件

Read the relevant file in the following cases:

File	When
`references/turborepo-deploy.md`	Turborepo/monorepo build issues
`references/deploy-verify.md`	Deploy loop details, Bun/Hono/Next.js health check patterns
`references/provisioning.md`	New service provisioning templates
`references/multi-tenant-env.md`	Bulk env update, isolation verification
`references/container-exec.md`	SSH patterns, file editing, container debug
`references/api.md`	All Coolify REST API endpoints (if MCP unavailable)

在以下场景中阅读对应的参考文件：

文件	适用场景
`references/turborepo-deploy.md`	Turborepo/单体仓库构建问题
`references/deploy-verify.md`	部署循环详情、Bun/Hono/Next.js健康检查模式
`references/provisioning.md`	新服务配置模板
`references/multi-tenant-env.md`	批量环境变量更新、隔离性验证
`references/container-exec.md`	SSH模式、文件编辑、容器调试
`references/api.md`	所有Coolify REST API端点（当MCP不可用时）