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 应用作根目录的目录。如果文件位于根目录，请使用 /，或者指定子文件夹（例如，对于 monorepo 使用 /backend）。
• Docker Compose 位置： 输入您的 Docker Compose 文件的路径，此路径将与基础目录结合。确保文件扩展名完全匹配，否则 Coolify 将无法加载它。

设置好上述所有设置后，单击 继续 按钮。

使服务对外部世界可用

在知识库中阅读有关 将服务暴露给互联网 的更多信息。

高级配置

使用环境变量和共享变量

在 Coolify 中，您可以按照 Docker Compose 知识库 中的详细说明轻松配置这些变量。

存储

您可以在 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
    ...

网络

当您部署 Docker Compose 堆栈时，Coolify 会自动为堆栈中的所有服务创建一个隔离的桥接网络（以您的资源 UUID 命名，例如 ewc08w0）。所有服务都可以使用其服务名称作为主机名相互通信（例如 http://backend:8080）。

Coolify 还将其反向代理（Traefik）连接到此网络，以便将外部流量路由到您的服务。

不要定义自定义网络

例如，请不要这样做：

services:
  frontend:
    networks:
      - my-network
  backend:
    networks:
      - my-network

networks:
  my-network:
    driver: bridge

当您定义自定义网络时，您的容器将同时位于两个网络上——Coolify 管理的网络和您的自定义网络。Traefik 仅位于 Coolify 管理的网络上，但会非确定性地选择路由到哪个网络 IP。如果它选择了自定义网络 IP，则无法访问您的容器，请求将无限挂起或返回 504 网关超时。

此行为是间歇性的——它可能在一次部署后正常工作，而在下一次部署后失效，具体取决于 Traefik 选择的 IP。请参阅 #4483、#6215、#6153。

相反，只需完全删除 networks: 部分：

services:
  frontend:
    ...
  backend:
    ...

Coolify 自动创建的网络已经提供了服务间通信。

连接到预定义网络

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

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

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

原始 Docker Compose 部署

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

标签

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

构建参数

在使用 Docker Compose 构建镜像时，Coolify 可以将构建参数注入到您的构建过程中。您可以在应用程序的 高级 菜单中配置这些设置。

将构建参数注入 Dockerfile

控制 Coolify 是否在构建过程中自动注入构建参数。如果您想在 Dockerfile 中完全控制构建参数，请在高级菜单中禁用此选项。

• 启用（默认）： Coolify 自动注入构建参数
• 禁用： 您在 Dockerfile 中自行管理 ARG 语句

在构建中包含源代码提交

控制是否在构建中包含 SOURCE_COMMIT 变量（Git 提交哈希）。默认情况下禁用此选项，以保留提交之间的 Docker 构建缓存。如果您的构建过程需要提交哈希，您可以在高级菜单中启用它。

• 禁用（默认）： 不包含 SOURCE_COMMIT，提高缓存利用率
• 启用： 将 SOURCE_COMMIT 作为构建参数包含在内

已知问题及解决方案