向 Coolify 添加新服务模板

Coolify 中的服务是由普通 docker-compose 文件和一些 Coolify 魔法组成的模板。

1. 添加元数据

   在 docker-compose 文件的顶部，添加以下元数据：

   # documentation: https://docs.example.com/
   # slogan: 服务的简要描述
   # category: 一个词，宽泛的应用类型
   # tags: tag1,tag2,tag3
   # logo: svgs/your-service.svg
   # port: 1234

   • documentation: 服务官方文档的链接
   • slogan: 服务的简短描述
   • category: 一个词的宽泛应用类型
   • tags: 用于提高可搜索性的逗号分隔列表
   • logo: 服务徽标的文件路径（见步骤 3）
   • port: 服务的主要入口点端口

2. 创建 docker-compose 文件

   在元数据下方，添加您的 docker-compose 配置。在此处使用 Coolify 的环境变量魔法 here。

   示例：

   services:
     app:
       image: your-service-image:tag
       environment:
         - DATABASE_URL=${COOLIFY_DATABASE_URL}
       volumes:
         - ${COOLIFY_VOLUME_APP}:/data

   使用必需的环境变量： 在创建服务模板时，将关键配置标记为必需，以改善用户体验：

   services:
     app:
       image: your-service:latest
       environment:
         # Required - critical configuration that must be set by the user
         - DATABASE_URL=${DATABASE_URL:?}
         - API_KEY=${API_KEY:?}
   
         # Required with sensible defaults - improves usability
         - PORT=${PORT:?8080}
         - LOG_LEVEL=${LOG_LEVEL:?info}
   
         # Optional - features that can be left empty
         - DEBUG=${DEBUG:-false}
         - CACHE_TTL=${CACHE_TTL:-3600}

   这有助于用户了解哪些配置是必需的，并防止部署失败。

3. 添加徽标

   • 为您的服务创建或获取 SVG 徽标（强烈推荐的格式）
   • 如果无法使用 SVG，则最后使用高质量的 .webp 或 JPG
   • 将徽标文件添加到 Coolify 仓库中的 svgs 文件夹
   • 徽标文件名必须与 docker-compose 服务名称完全匹配
     • 例如，如果您的服务名称是 wordpress，则您的徽标应为 wordpress.svg，最终路径为 svgs/wordpress.svg，在 logo 元数据中使用此路径。

4. 测试您的模板

   在 Coolify 中使用 Docker Compose Empty 部署选项来测试您的模板。此过程模拟了一键服务部署。

5. 提交拉取请求

   一旦您的模板正常工作：

   • 打开 PR
   • 在 /templates/compose 下添加您的新 <service>.yaml compose 文件
   • 在 svgs 文件夹中包含徽标文件

向 Coolify 文档添加新服务模板

一旦您的服务模板合并到 Coolify 中，在 Coolify 文档中添加其文档也很重要。 在 Coolify 文档贡献部分 中，我们解释了如何贡献并在自己的 PC 上运行文档。

一旦您准备好本地设置，请按照以下步骤添加您的新服务：

1. 在 /docs/public/images/services/ 下添加服务徽标

   • 使用与您的服务 slug 相同的基名，例如 my-service.svg 或 my-service-logo.svg。图标解析器尝试 <slug>-logo、<slug>_logo、<slug>logo，然后是裸 <slug>，然后是标题的相同变体。
   • 首选 SVG；否则 WebP，然后 PNG。避免对徽标使用 JPEG。

2. 创建文档文件

   创建 /docs/services/<service-slug>.md。slug 必须是小写且连字符分隔的，并且必须与文件名匹配。使用此前元数据：

   ---
   title: "服务名称"
   description: "出现在服务卡片和搜索结果中的简短描述。"
   og:
     description: "SEO/社交卡片描述（可选，比 `description` 更长）。"
   category: "分析"
   icon: "/docs/images/services/service-name-logo.svg"
   ---

   字段	必需	备注
   title	是	卡片上显示的显示名称
   description	是	用作卡片描述并在 all.md 中使用
   category	是	确定服务在 all.md 中出现的标题以及概述中的过滤器
   icon	可选	仅在自动解析无法找到您的徽标时设置
   og.description	可选	用于社交/SEO 元标签的较长描述
   disabled	可选	设置为 true 以从列表中隐藏服务，同时保持通过直接 URL 可访问

3. 编写文档

   在前元数据下开始编写您的文档。使用以下模板作为起点：

   # 服务名称
   
   ![服务名称](/docs/images/services/service-name-logo.svg)
   
   ## 什么是服务名称？
   
   简要描述和使用案例。
   
   ## 链接
   
   - [官方网站](https://example.com?utm_source=coolify.io)
   - [GitHub](https://github.com/example/repo?utm_source=coolify.io)

   仅对受益于可缩放视图的截图使用 <ZoomImage>，而不是用于徽标。

4. 重新生成列表（可选 — 在 dev/build 上自动发生）

   bun run generate:services

   这将刷新 src/generated/services.json 和 docs/services/all.md。将两个重新生成的文件与您的新服务页面一起提交。

5. 提交拉取请求

   • 目标分支为 next
   • 使用 bun run dev 验证服务是否正确渲染，包括列表卡片、过滤器类别和 /services/all 中的条目

请求新服务

如果您希望在 Coolify 中看到某个服务模板：

1. 在 GitHub 讨论 中搜索现有请求。
2. 如果该服务已被请求，请为其投票。如果没有，请创建新请求。