跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 dokploy-docker-compose

Dokploy Docker Compose

Dokploy上部署多克编曲堆栈(自办VPS部署平台)的综合指南. 每当用户提到多克普洛伊,向一VPS部署多克编译器,在自托管服务器上部署多克编译器(docker-compose.yml)的应用程序,或者在多克普洛伊上运行的多克编译器堆栈出故障时使用此技能. 包括编译(上)和应用程序(Git)的部署类型、量战略、联网、环境变量、输入容器、健康检查、与Traefik的域,以及诸如EAI_AGAIN、不允许、不健康的容器和JWT/配置问题等常见出错。 在向 Dokploy 部署任何多功能 Docker 堆栈时也适用 .

80 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

Dokploy上部署多克编曲堆栈(自办VPS部署平台)的综合指南. 每当用户提到多克普洛伊,向一VPS部署多克编译器,在自托管服务器上部署多克编译器(docker-compose.yml)的应用程序,或者在多克普洛伊上运行的多克编译器堆栈出故障时使用此技能. 包括编译(上)和应用程序(Git)的部署类型、量战略、联网、环境变量、输入容器、健康检查、与Traefik的域,以及诸如EAI_AGAIN、不允许、不健康的容器和JWT/配置问题等常见出错。 在向 Dokploy 部署任何多功能 Docker 堆栈时也适用 .

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Dokploy Docker Compose Deployment Skill、Overview、Part 1: Service Types、Compose (Docker Compose mode)、Stack (Docker Swarm mode)、Application (Git) Deployment。 其中含规范建议的小节:分步指令。

文件分析

文件分析:除 SKILL.md 外,正文引用了 scripts/tool、references/init-container-patterns.md、references/sop-compose-deployment.md、references/sop-git-deployment.md、references/librechat-example.md、references/signoz-example.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Comprehensive guide for deploying Docker Compose stacks on Dokploy (self-hosted VPS deployment platform). Use this skill whenever the user mentions Dokploy, deploying Docker Compose to a VPS, deploying applications with docker-compose.yml on a self-hosted server, or when troubleshooting Docker Compose stacks running on Dokploy. Covers both Compose (stack) and Application (Git) deployment types, volume strategies, networking, environment variables, init containers, healthchecks, domains with Traefik, and troubleshooting common errors like EAI_AGAIN, permission denied, unhealthy containers, and JWT/config issues. Also applies when deploying any multi-service Docker Compose stack to Dokploy.

Dokploy Docker Compose Deployment SkillOverviewPart 1: Service TypesCompose (Docker Compose mode)Stack (Docker Swarm mode)Application (Git) DeploymentPart 2: Volume StrategyNamed Volumes (Best for databases and large data)`../files/` Bind Mounts (Best for config files and small data)Step 1: find your container name (Dokploy names them <stack>-<service>-1)Step 2: inspect that container to see where ../files/ maps on the hostFile Mounts (Dokploy UI — for pasting config content directly)

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
dokploy-docker-compose
description
Comprehensive guide for deploying Docker Compose stacks on Dokploy (self-hosted VPS deployment platform). Use this skill whenever the user mentions Dokploy, deploying Docker Compose to a VPS, deploying applications with docker-compose.yml on a self-hosted server, or when troubleshooting Docker Compose stacks running on Dokploy. Covers both Compose (stack) and Application (Git) deployment types, volume strategies, networking, environment variables, init containers, healthchecks, domains with Traefik, and troubleshooting common errors like EAI_AGAIN, permission denied, unhealthy containers, and JWT/config issues. Also applies when deploying any multi-service Docker Compose stack to Dokploy.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 7
  • scripts/tool
  • references/init-container-patterns.md
  • references/sop-compose-deployment.md
  • references/sop-git-deployment.md
  • references/librechat-example.md
  • references/signoz-example.md
  • references/healthchecks.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「dokploy-docker-compose」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-0fdbb4386a59c18b-Dokploy-Docker-%E7%BC%96%E6%9B%B2.html
请存为 .cursor/skills/dokploy-docker-compose/SKILL.md 或 .claude/skills/dokploy-docker-compose/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/trfi/skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/trfi/skills' --list

npx skills add 'https://github.com/trfi/skills' --skill 'dokploy-docker-compose'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: dokploy-docker-compose description: > Comprehensive guide for deploying Docker Compose stacks on Dokploy (self-hosted VPS deployment platform). Use this skill whenever the user mentions Dokploy, deploying Docker Compose to a VPS, deploying applications with docker-compose.yml on a self-hosted server, or when troubleshooting Docker Compose stacks running on Dokploy. Covers both Compose (stack) and Application (Git) deployment types, volume strategies, networking, environment variables, init containers, healthchecks, domains with Traefik, and troubleshooting common errors like EAI_AGAIN, permission denied, unhealthy containers, and JWT/config issues. Also applies when deploying any multi-service Docker Compose stack to Dokploy. --- # Dokploy Docker Compose Deployment Skill ## Overview Dokploy is a self-hosted deployment platform that manages Docker containers on a VPS. It supports two compose modes (Docker Compose and Docker Stack) and requires specific patterns to work reliably. **Quick decision tree:** - Single-repo app with `Dockerfile`? → **Application (Git)** deployment - Pre-built images or multi-service stack? → **Compose** deployment - Need a public HTTPS domain? → **Domains tab** (Dokploy auto-injects Traefik labels) - Need isolated networking per-app? → Enable **Isolated Deployments** in UI - Config files needed without SSH? → **File Mounts** in Advanced → Mounts - Complex stack needing generated configs + binary downloads? → **Init Containers** pattern --- ## Part 1: Service Types ### Compose (Docker Compose mode) Best for: multi-service stacks using pre-built images. Standard `docker compose up` behavior. Key constraints vs running locally: - Each deploy via AutoDeploy does a **`git clone`** which clears the repository directory — any relative path like `./config.yaml` will be **empty or missing** after the first push - Never use `container_name:` on services — it breaks Dokploy's logs, metrics, and monitoring features - Relative bind mounts (`./data`) work only on first deploy; use `../files/` or named volumes instead ### Stack (Docker Swarm mode) Docker Stack mode for orchestrated deployments. Key differences from Compose mode: - **No `build:` directive** — must use pre-built images from a registry - Traefik labels must go under **`deploy.labels`**, not directly under `labels` - Add `--with-registry-auth` flag in Advanced → Command if using private registries with replicas ### Application (Git) Deployment Best for: source code you build from a Dockerfile. Steps: Create Service → Application → Source: Git → Build Type: Dockerfile → configure Volumes and Ports in Advanced. --- ## Part 2: Volume Strategy ⚠️ **Critical Dokploy rule:** Absolute host paths (e.g., `/opt/myapp/`) are **cleaned up during deployments**. Never use them. Use the `../files/` folder or named volumes instead. ### Named Volumes (Best for databases and large data) ```yaml services: db: image: postgres:16 volumes: - db-data:/var/lib/postgresql/data volumes: db-data: ``` Docker manages these. Supports **automated backups** via Dokploy's Volume Backups feature. Best for databases, large datasets. ### `../files/` Bind Mounts (Best for config files and small data) Dokploy provides a persistent `../files/` folder that survives deployments: ```yaml volumes: - ../files/my-config:/etc/myapp/config ✅ persists across deploys - ../files/my-database:/var/lib/mysql ✅ persists across deploys - ./config.yaml:/app/config.yaml ❌ wiped on each AutoDeploy (git clone) - /opt/myapp/data:/app/data ❌ absolute paths are cleaned up by Dokploy ``` No direct host file access needed. Best for config files, small datasets. No backup support. **Host path on the VPS:** `../files/` maps to a `files/` folder inside Dokploy's project directory on the host. To find the exact path after first deploy, SSH in and run: ```bash # Step 1: find your container name (Dokploy names them --1) docker ps --format "table {{.Names}}\t{{.Image}}" | grep # Step 2: inspect that container to see where ../files/ maps on the host docker inspect | grep -A2 '"Source"' ``` Or check the **Docker tab** in the Dokploy UI — the container name is listed there directly. ### File Mounts (Dokploy UI — for pasting config content directly) In **Advanced → Mounts → Add Mount → File Mount**: - **Content**: paste the file text - **File Path**: just the filename (e.g., `config.yaml`) - **Mount Path**: full container path (e.g., `/app/config/config.yaml`) ✅ Best for: config files you want to manage entirely in Dokploy UI ❌ Not for: binary files, files needing runtime generation, files > a few KB ### Init Container Pattern (for complex stacks needing generated configs) When a stack needs multiple config files written at runtime, or binary downloads, use an alpine init container that writes files into a shared named volume before the main service starts: ```yaml services: my-conf: image: alpine:3.20 command: - /bin/sh - -lc - | cat > /config/app.yaml <<'YAML' key: value YAML apk add --no-cache wget && wget -O /scripts/tool "https://..." volumes: - app-config:/config - app-scripts:/scripts restart: "no" # MUST exit after running app: depends_on: my-conf: condition: service_completed_successfully volumes: - app-config:/etc/app/ - app-scripts:/usr/local/scripts/ ``` **Shell escaping:** Use `$$` inside compose heredocs — `$$(uname -s)` not `$(uname -s)`. See `references/init-container-patterns.md` for complete examples. ### Choosing the Right Volume Method | Need | Method | |------|--------| | Database data | Named volume | | Automated backups to S3 | Named volume (only option) | | Config file — manage in UI | File Mount | | Config file — large or complex | `../files/` bind mount | | Generated configs + binaries | Init container → named volume | | ❌ Do NOT use | Absolute host paths, `./` relative paths | --- ## Part 3: Environment Variables ### How Dokploy handles env vars Variables set in the **Environment tab** are written to a `.env` file in the same directory as `docker-compose.yml`. They are **NOT automatically injected** into containers. You must explicitly load them in your compose YAML using one of two approaches: **Option A — Load all variables (simpler for many vars):** ```yaml services: app: env_file: - .env # loads every variable from Dokploy's Environment tab ``` **Option B — Select specific variables:** ```yaml services: app: environment: - JWT_SECRET=${JWT_SECRET} - DATABASE_URL=${DATABASE_URL} - PORT=3000 # hardcoded values also work ``` ⚠️ If you use `environment:` with explicit variables, only those listed variables are passed. Any variable set in the UI but not listed here will be silently ignored. **Recommendation:** For stacks with many secrets (LibreChat, etc.) use `env_file: - .env` on each service that needs them. For stacks where services need different subsets, use explicit `${VAR}` refs. ### Generate secure values ```bash openssl rand -hex 32 # 64-char hex string (for keys like CREDS_KEY) openssl rand -hex 16 # 32-char hex string (for IVs like CREDS_IV) ``` --- ## Part 4: Domains & Traefik Routing Dokploy uses Traefik as a reverse proxy. There are two ways to expose services via a domain. ### Method 1: Dokploy Domains UI (Recommended — since v0.7.0) Go to your service → **Domains tab** → **Add Domain**. Dokploy **automatically injects** the correct Traefik labels into your compose file at deploy time. You never touch the labels manually. ⚠️ **Deploy first, then add domain.** The Domains tab requires a running service — you can't add a domain before the first deploy. - Use `expose:` (not `ports:`) in your compose YAML when routing via domain - Use **Preview Compose** button to see the final compose file with auto-injected labels - **HTTPS**: enable for direct DNS (A record → VPS); disable if behind Cloudflare proxy (set Cloudflare SSL/TLS to Full) ```yaml services: app: image: myapp:latest expose: - 3000 # container-only; Traefik routes via domain, no host port needed ``` ### Method 2: Manual Traefik Labels (Advanced) For fine-grained control, add labels directly in your compose file. Requires connecting to `dokploy-network` (the shared Traefik network): ```yaml services: frontend: image: myapp:latest expose: - 3000 networks: - dokploy-network labels: - traefik.enable=true - traefik.http.routers.my-unique-name.rule=Host(`app.yourdomain.com`) - traefik.http.routers.my-unique-name.entrypoints=websecure - traefik.http.routers.my-unique-name.tls.certResolver=letsencrypt - traefik.http.services.my-unique-name.loadbalancer.server.port=3000 networks: dokploy-network: external: true ``` **For Docker Stack** — labels go under `deploy.labels`: ```yaml services: frontend: image: myapp:latest deploy: labels: - traefik.enable=true - traefik.http.routers.my-app.rule=Host(`app.yourdomain.com`) - traefik.http.services.my-app.loadbalancer.server.port=3000 networks: - dokploy-network ``` ### Isolated Deployments Enable this in the Dokploy UI (toggle on the Compose service page) to give your stack its own private network instead of sharing `dokploy-network`. This is: - Required when running **multiple instances** of the same app (e.g., two WordPress sites) - Safer — services aren't visible across other stacks - Automatic — Dokploy handles all network creation and Traefik wiring When Isolated Deployments is enabled, you don't need to add `dokploy-network` manually. All open-source templates shipped with Dokploy have this enabled by default. ⚠️ If NOT using Isolated Deployments, only the domain-targeted service gets `dokploy-network` added automatically. Other services in the stack won't be on that network unless you add it manually. --- ## Part 5: Networking & DNS (EAI_AGAIN Fix) The most common multi-service error: ``` getaddrinfo EAI_AGAIN mongodb ``` Container can't resolve another service's hostname. Causes: race condition or DNS confusion. **Fix 1 — Healthchecks + proper `depends_on`** (prevents race conditions): ```yaml services: api: depends_on: mongodb: condition: service_healthy # waits until healthy, not just started mongodb: healthcheck: test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"] interval: 10s retries: 5 start_period: 10s ``` **Fix 2 — Explicit custom network** (guarantees DNS between services): ```yaml networks: app-net: driver: bridge services: api: networks: [app-net] mongodb: networks: [app-net] ``` ⚠️ Avoid using `container_name:` as a DNS workaround — it breaks Dokploy monitoring features. Use service names for inter-container communication instead. --- ## Part 6: Healthchecks Add a `healthcheck` to every dependency service (databases, caches, queues). Pair it with `depends_on: condition: service_healthy` on services that need them — this prevents race conditions where a service starts before its dependency is ready. **Example:** ```yaml services: postgres: image: postgres:16 healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5 app: depends_on: postgres: condition: service_healthy ``` --- ## Part 7: Updating Deployed Services ### Manual update (public repos you don't own) 1. Go to Deployments tab → Click **Deploy** 2. If Docker cache is stale: look for "Redeploy without Cache" or clear Build Cache in System Settings ### Automatic updates via Webhook 1. Copy Webhook URL from **Deployments tab** 2. Add it to your GitHub/GitLab/Gitea repo Settings → Webhooks 3. Every push to the branch triggers an automatic deploy --- ## Part 8: Common Errors & Fixes | Error | Cause | Fix | |-------|-------|-----| | `getaddrinfo EAI_AGAIN ` | Race condition / DNS | Add healthcheck + `condition: service_healthy`; use custom network | | Config file empty after redeploy | `./` relative path wiped by git clone | Use `../files/` bind mount or File Mount in UI | | `JwtStrategy requires a secret or key` | JWT env var not injected | Add `env_file: - .env` or explicit `- JWT_SECRET=${JWT_SECRET}`; **Redeploy** (not Restart) | | `ENOENT: no such file or directory` | Config file not mounted | Use File Mount in Advanced → Mounts, or `../files/` bind mount | | `permission denied` on volume | Old volume from different user | Rename volume (e.g., `data-v2`) to force fresh creation | | Container `is unhealthy` | Wrong healthcheck for image | Match healthcheck command to image type; see Part 6 | | Logs/metrics missing in Dokploy | `container_name:` set on service | Remove `container_name:` — it breaks Dokploy's monitoring | | Services can't see each other after adding domain | Not on same network | Use Isolated Deployments, or manually add `dokploy-network` to all services | --- ## Part 9: Reference Files - `references/sop-compose-deployment.md` — step-by-step SOP for any multi-service Compose stack - `references/sop-git-deployment.md` — deploying from Git with Dockerfile - `references/librechat-example.md` — LibreChat: JWT secrets, MongoDB DNS, librechat.yaml mounting - `references/signoz-example.md` — SigNoz: init containers, ClickHouse, Zookeeper migration - `references/init-container-patterns.md` — init container patterns with heredocs and binary downloads - `references/healthchecks.md` — healthcheck snippets for common services --- ## Quick Checklist: Adapting any docker-compose.yml for Dokploy - [ ] **Remove all `container_name:`** — breaks Dokploy logs and metrics - [ ] **Replace `./` relative bind mounts** with `../files/` or named volumes - [ ] **No absolute host paths** (`/opt/...`) — they get cleaned up on deploy - [ ] **Remove `user: "${UID}:${GID}"`** — causes permission errors in Dokploy - [ ] **Remove `env_file: - ./.env`** — file won't exist; use `env_file: - .env` (no `./`) or `${VAR}` syntax - [ ] **Add `env_file: - .env`** OR explicit `${VAR}` refs for every secret — env vars aren't auto-injected - [ ] **Add healthchecks** to all database/dependency services - [ ] **Update `depends_on`** to use `condition: service_healthy` instead of just service name - [ ] **For domains**: use Dokploy's Domains tab (Method 1) unless you need custom Traefik config - [ ] **Use `expose:`** (not `ports:`) for services routed via Traefik domain - [ ] **Declare all named volumes** at the bottom of the file

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…