Docker Compose 让您能够轻松部署多个 Docker 容器并配置它们。

使用 Docker Compose 构建包，您可以使用自己的 Docker Compose 文件（即 docker-compose.y[a]ml）作为单一可信来源，完全控制应用程序在 Coolify 上的构建和部署方式。

如何使用 Docker Compose？

1. 在 Coolify 中创建新资源

在 Coolify 仪表板上，打开您的项目并点击创建新资源按钮。

2. 选择您的部署选项

A. 如果您的 Git 仓库是公开的，选择公共仓库选项。

B. 如果您的仓库是私有的，您可以选择Github App或部署密钥。（这些方法需要额外配置。如果需要，您可以查看设置 Github App ↗ 或 部署密钥 ↗ 的指南。）

3. 选择您的 Git 仓库

如果您使用的是公共仓库，在提示时粘贴您的 GitHub 仓库的 URL。所有其他选项的步骤都非常相似。

4. 选择构建包

Coolify 默认使用 Nixpacks。点击 Nixpacks 选项，然后从下拉菜单中选择Docker Compose作为您的构建包。

5. 配置构建包

• 分支： Coolify 会自动检测您仓库中的分支。
• 基础目录： 输入 Coolify 应使用的根目录。如果您的文件在根目录，则使用 /，或者指定一个子文件夹（如单体仓库中的 /backend）。
• Docker Compose 位置： 输入您的 Docker Compose 文件的路径，此路径与基础目录结合使用。确保文件扩展名完全匹配，否则 Coolify 将无法加载它。

一旦您将所有上述设置设为正确的详细信息，点击继续按钮。

高级配置

定义环境变量

Coolify 会自动检测您的 compose 文件中提到的环境变量并在 UI 中显示它们。例如：

services:
  myservice:
    environment:
      - SOME_HARDCODED_VALUE=hello # 传递给容器，但在 Coolify 的 UI 中不可见。
      - SOME_VARIABLE=${SOME_VARIABLE_IN_COOLIFY_UI} # 在 UI 中创建一个可编辑的未初始化变量。
      - SOME_DEFAULT_VARIABLE=${OTHER_NAME_IN_COOLIFY:-hello} # 设置一个可编辑的默认值 "hello"。

必填环境变量

您可以使用 :? 语法将环境变量标记为必填。必填变量必须在部署前设置，如果为空，它们将在 Coolify 的 UI 中用红色边框高亮显示。

services:
  myapp:
    environment:
      # 必填变量 - 未设置将导致部署失败
      - DATABASE_URL=${DATABASE_URL:?}
      - API_KEY=${API_KEY:?}

      # 带默认值的必填变量 - 在 UI 中预填充但可以更改
      - PORT=${PORT:?3000}
      - LOG_LEVEL=${LOG_LEVEL:?info}

      # 可选变量 - 标准行为
      - DEBUG=${DEBUG:-false}
      - CACHE_TTL=${CACHE_TTL:-3600}

主要行为：

• 必填变量 (${VAR:?}) 显示在环境变量列表的首位，为空时显示红色边框
• 带默认值的必填变量 (${VAR:?default}) 使用默认值预填充，但仍可编辑
• 可选变量 (${VAR:-default}) 使用标准的 Docker Compose 行为

如果在部署期间未设置必填变量：

• Coolify 将在 UI 中高亮显示缺失的变量
• 在提供所有必填变量之前，部署将被阻止
• 清晰的错误消息指导用户修复配置

这种验证发生在容器创建之前，防止部分部署和运行时故障。

Coolify 的魔法环境变量

Coolify 可以使用以下语法为您生成动态环境变量：SERVICE_<TYPE>_<IDENTIFIER>。

注意！

基于 Git 源的 Compose 文件中对魔法环境变量的支持已在 Coolify v4.0.0-beta.411 版本中添加

类型包括：

• FQDN： 为服务生成完全限定域名。
• URL： 基于定义的 FQDN 生成 URL。
• USER： 创建随机用户名。
• PASSWORD： 创建密码（使用 PASSWORD_64 获取 64 位长密码）。
• BASE64： 生成随机字符串（使用 BASE64_64 或 BASE64_128 获取更长的字符串）。
• REALBASE64： 生成 base64 编码的随机字符串（使用 REALBASE64_64 或 REALBASE64_128 获取更长的字符串）。

每个生成的变量在您的栈中的所有服务中都是一致的，并显示在 Coolify 的 UI 中（除了固定的 FQDN 和 URL）。

例如，如果您的应用程序 UUID 是 vgsco4o，并且您在通配符域名 http://example.com 上部署 Appwrite，您可能会包含：

services:
  appwrite:
    environment:
      # 生成 FQDN: http://appwrite-vgsco4o.example.com/v1/realtime
      - SERVICE_FQDN_APPWRITE=/v1/realtime

      # 使用 FQDN 作为 _APP_URL。
      - _APP_URL=$SERVICE_FQDN_APPWRITE

      # 代理到端口 3000。
      - SERVICE_FQDN_APPWRITE_3000

      # 代理 API 请求到端口 2000。
      - SERVICE_FQDN_API_2000=/api

      # 生成并注入密码。
      - SERVICE_SPECIFIC_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
  not-appwrite:
    environment:
      # 重用 Appwrite 服务的密码。
      - APPWRITE_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
      # 为此服务生成新的 FQDN。
      - SERVICE_FQDN_API=/api

存储

您可以在 compose 文件中设置存储，并为 Coolify 提供一些额外选项。

创建空目录

定义具有主机绑定的目录并通知 Coolify 创建它们：

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    volumes:
      - type: bind
        source: ./srv
        target: /srv
        is_directory: true # 指示 Coolify 创建目录。

创建带内容的文件

指定具有预定义内容的文件，甚至可以包含来自环境变量的动态值：

services:
  filebrowser:
    image: filebrowser/filebrowser:latest
    environment:
      - POSTGRES_PASSWORD=password
    volumes:
      - type: bind
        source: ./srv/99-roles.sql
        target: /docker-entrypoint-initdb.d/init-scripts/99-roles.sql
        content: |
          -- 注意：在生产环境中更改这些密码！
           \set pgpass `echo "$POSTGRES_PASSWORD"`

           ALTER USER authenticator WITH PASSWORD :'pgpass';
           ALTER USER pgbouncer WITH PASSWORD :'pgpass';

排除健康检查

如果某个服务不应成为整体健康检查的一部分（例如，一次性迁移服务），请将 exclude_from_hc 选项设置为 true：

services:
  some-service:
    exclude_from_hc: true
    ...

连接到预定义网络

默认情况下，每个 compose 栈都部署到一个以您的资源 UUID 命名的单独网络中。这种设置允许栈中的每个服务相互通信。

如果您想跨不同的栈连接服务（例如，将应用程序链接到单独的数据库），请在服务栈页面上启用连接到预定义网络选项。

请注意，当引用另一个栈中的服务时，必须使用全名（如 postgres-<uuid>）。

原始 Docker Compose 部署

对于高级用户，Coolify 提供了"原始 Compose 部署"模式。此选项允许您直接部署 Docker Compose 文件，而无需 Coolify 的许多额外配置。

警告

此模式专为熟悉 Docker Compose 的高级用户设计。

标签

Coolify 会自动向您的应用程序添加这些标签（如果尚未设置）：

labels:
  - coolify.managed=true
  - coolify.applicationId=5
  - coolify.type=application

要启用 Coolify 的代理（Traefik），还请包含这些标签：

labels:
  - traefik.enable=true
  - "traefik.http.routers.<unique_router_name>.rule=Host(`shadowarcanist.com`) && PathPrefix(`/`)"
  - traefik.http.routers.<unique_router_name>.entryPoints=http

已知问题和解决方案

1. 访问应用程序域名显示"无可用服务器"

如果您在访问网站时看到"无可用服务器"错误，这很可能是由于容器的健康检查导致的。

在服务器终端上运行 docker ps 来检查您的容器是否不健康或仍在启动中。

要解决此问题，请修复导致容器不健康的问题或移除健康检查。