OCurrent/OCaml-CI 项目本地开发环境搭建指南

前言

OCurrent/OCaml-CI 是一个基于 OCurrent 框架构建的持续集成系统，专门为 OCaml 项目设计。本文将详细介绍如何在本地开发环境中搭建和运行 OCaml-CI 系统，帮助开发者理解其工作原理并进行二次开发。

核心概念理解

在开始搭建前，我们需要了解几个关键概念：

1. OCurrent 框架：一个用于构建自动化管道的 OCaml 库
2. GitHub App：OCaml-CI 通过 GitHub App 与代码仓库交互
3. 服务架构：系统由两个主要服务组成 - ocaml-ci-service（后端服务）和 ocaml-ci-web（前端界面）

环境准备

1. 创建 GitHub App

OCaml-CI 依赖 GitHub App 实现与 GitHub 的交互，因此首先需要创建自己的 GitHub App：

1. 访问 GitHub 应用设置页面

2. 创建新应用时，需要配置以下权限：

   • 仓库权限：
     • Checks: 读写
     • Commit statuses: 读写
     • Contents: 只读
     • Metadata: 只读
     • Pull requests: 只读
   • 订阅事件：
     • Create
     • Pull request
     • Push

3. 配置 Webhook 指向本地开发环境（可使用 smee.io 等工具转发）

2. 准备必要文件

运行本地环境需要以下文件：

1. private-key.pem：GitHub App 的私钥文件
2. webhook-secret：包含 Webhook 密钥的文件

这些文件需要存放在同一目录下，后续会通过环境变量指定该目录路径。

配置与运行

1. Caddy 反向代理配置

创建 /etc/caddy/Caddyfile 文件，配置如下：

{
    log default {
        level WARN
    }
}

http://localhost:8100 {
    reverse_proxy service:8080  # 后端服务
}

http://localhost {
    reverse_proxy web:8090     # 前端界面
}

此配置将：

• 将 8100 端口的请求转发到后端服务
• 将默认 80 端口的请求转发到前端界面

2. 启动服务

可以通过两种方式启动服务：

方式一：直接指定环境变量

APP_ID=你的应用ID \
ALLOW_LIST=允许的GitHub账号(逗号分隔) \
SECRETS_DIR=密钥文件目录路径 \
docker compose up

方式二：使用 .env 文件

在项目根目录创建 .env 文件：

APP_ID=359343
ALLOW_LIST="yourusername,otheruser"
SECRETS_DIR=/path/to/secrets/

然后简单运行：

docker compose up

3. Webhook 转发配置

为了接收 GitHub 的 Webhook 通知，需要运行 smee 客户端：

smee --url https://smee.io/你的频道ID --path /webhooks/github --port 8100

确保 GitHub App 设置中的 Webhook URL 指向正确的地址。

数据库迁移管理

OCaml-CI 使用 omigrate 工具管理数据库迁移：

1. 创建新迁移：

omigrate create --dir migrations 迁移名称

这会在 migrations 目录下生成两个文件：

• up：应用迁移的 SQL
• down：回滚迁移的 SQL

2. 注意：服务启动时必须添加 --migration-path 参数才会执行迁移。

访问服务

成功启动后：

• 管理界面：http://localhost:8100
• 用户界面：http://localhost

开发建议

1. 调试技巧：可以通过调整 Caddyfile 中的日志级别获取更多调试信息
2. 安全注意：私钥文件应妥善保管，不要提交到版本控制系统
3. 性能优化：本地开发时可以考虑减少并行构建数量以降低资源消耗

通过本文的指导，开发者应该能够在本地搭建完整的 OCaml-CI 开发环境，为后续的功能开发和问题排查打下基础。