namshi/roger

Roger

镜像概述和主要用途

Roger是一个简单但功能强大的Docker容器构建服务器，通过配置即可实现项目的自动构建（如定时构建或GitHub拉取请求触发）。它部署简便，内置与GitHub、Docker Registry等平台的集成，支持私有仓库构建和推送至Docker Hub或私有 registry，提供Web界面监控构建过程，并支持多种通知和制品发布方式。

核心功能和特性

• 持续集成与自动构建：支持定时构建、GitHub推送/标签/拉取请求触发构建
• 多平台集成：无缝对接GitHub（Webhook、状态更新）和Docker Registry（私有/公共）
• 灵活的项目配置：支持多项目构建、自定义Dockerfile路径、构建后钩子（如测试）
• 分支与标签过滤：可配置仅构建特定分支、标签或匹配正则表达式的分支/标签
• 多渠道通知：支持GitHub状态更新、Amazon SES邮件通知、Slack频道通知
• 制品发布：支持将构建产物上传至S3存储
• 构建优化：支持分离构建镜像和运行镜像，减小最终镜像体积
• API支持：提供完整API接口，用于管理项目、构建和触发构建
• 可扩展认证：支持通过Passport.js自定义认证机制

使用场景和适用范围

• 团队Docker镜像自动化构建流程
• 与GitHub工作流集成（如拉取请求验证、合并后自动构建）
• 私有仓库镜像构建与推送至私有Registry
• 需要构建后测试、通知和制品发布的CI/CD场景
• 多项目、多分支并行构建管理

详细的使用方法和配置说明

安装

1. 创建配置文件

首先创建config.yml配置文件：

yaml
auth:
  dockerhub: # Docker Hub推送凭证（如需推送到Docker Hub）
    username: user # Docker Hub用户名
    email: someone@gmail.com # 邮箱
    password: YOUR_DOCKERHUB_PASSWORD # 密码
  github: YOUR_GITHUB_TOKEN # GitHub访问令牌（用于克隆仓库和PR评论，需在https://github.com/settings/tokens/new创建）

2. 启动容器

运行以下命令启动Roger：

bash
docker run -ti -p 8080:8080 \
-v /tmp/logs:/tmp/roger-builds/logs \
-v $(pwd)/db:/db \
-v /path/to/your/config.yml:/config.yml \
-v /var/run/docker.sock:/tmp/docker.sock \
namshi/roger

3. 验证启动

启动成功后，日志将显示：

2015-01-27T17:52:50.827Z - info: using config: {...}}
Roger running on port 8080

此时可通过http://localhost:8080访问Web界面。

4. 触发首次构建

在GitHub仓库根目录添加build.yml：

yaml
redis: # 项目名称（将作为镜像名称）
  registry: registry.company.com # 私有registry地址（如127.0.0.1:5000）

访问http://localhost:8080/api/build?repo=YOUR_REPO_URL（如http://localhost:8080/api/build?repo=https://github.com/namshi/test-build）触发构建，Web界面将显示构建进度。

提示：若首次使用，可通过docker-compose up启动Roger开发环境，包含本地registry，无需额外配置registry。

配置参考

项目配置（build.yml）

项目配置文件build.yml位于仓库根目录，支持以下配置项：

yaml
redis: # 项目名称（镜像名称）
  dockerfilePath: some/subdir # Dockerfile路径（默认根目录）
  registry: 127.0.0.1:5001 # registry地址（不指定则默认127.0.0.1:5000；指定为dockerhub则推送到Docker Hub）
  revfile: somedir # 生成构建信息文件rev.txt的路径
  after-build: # 构建后钩子（在容器内运行，如测试）
    - ls -la
    - npm test
  notify: # 通知方式（支持github、emailSes、slack）
    - github
    - emailSes
    - slack
  publish: # 制品发布配置
    -
      to: s3 # 发布到S3
      copy: /src/build/public/ # 容器内待发布路径
      bucket: my-bucket # S3桶名称
      bucketPath: initial-path # S3路径前缀（如s3://my-bucket/initial-path）
      command: gulp build # 发布前执行的命令（如构建产物）
  build: # 构建镜像与运行镜像分离配置
    dockerfile: dockerfile.build # 构建镜像的Dockerfile
    extract: /src # 从构建镜像中提取的目录（用于构建运行镜像）

多项目构建

同一仓库可配置多个项目：

yaml
redis:
  dockerfilePath: src
redis-server:
  dockerfilePath: server/src

分支和标签过滤

仅对Webhook触发的构建生效，可配置：

• branches：允许构建的分支列表
• patterns：匹配分支/标签的正则表达式列表
• tags：是否允许所有标签构建（true/false）

示例：

yaml
redis:
  registry: dockerhub

settings:
  matching:
    branches:
      - master
      - develop
    patterns:
      - ^v\d+\.\d+\.\d+$ # 匹配v1.0.0格式的版本标签

另一个示例（允许master分支和所有标签）：

yaml
redis:
  registry: dockerhub

settings:
  matching:
    branches:
      - master
    tags: true

服务器配置（config.yml）

服务器配置文件需挂载到容器的/config.yml，支持以下配置项：

yaml
app: # 应用通用设置
  url: 'https://builds.yourcompany.com' # 可选，用于日志
  auth: ~ # 认证配置（默认关闭，见"配置认证"）
  defaultRegistry: registry.company.com # 默认registry（如127.0.0.1:5000）
builds:
  concurrent: 5 # 最大并行构建数（~表示禁用限制）
  retry-after: 30 # 检查队列构建的间隔（秒）
auth: # 第三方认证凭证
  dockerhub: # Docker Hub凭证
    username: odino
    email: alessandro.nadalin@gmail.com
    password: YOUR_DOCKERHUB_PASSWORD
  github: YOUR_SECRET_TOKEN # GitHub访问令牌
notifications: # 通知配置
  github: # GitHub状态通知
    token: '{{ auth.github }}' # 引用auth.github的值
  emailSes: # Amazon SES邮件通知
    accessKey: 1234 # AWS访问密钥
    secret: 5678 # AWS密钥
    region: eu-west-1 # 区域
    to: # 收件人列表
      - john.doe@gmail.com
      - committer # 特殊值，指代提交者邮箱
    from: builds@company.com # 发件人（需在SES验证）
  slack: # Slack通知
    global: 'true' # 是否全局启用
    channel: '#channel-name' # 频道
    icon_emoji: ':slack-emoji:' # 图标
    username: 'Roger' # 用户名
docker: # Docker客户端配置（基于dockerode）
  client:
    socketPath: '/tmp/docker.sock' # Docker socket路径（默认）
    # 可选配置：
    # host: __gateway__ # 通过netroute解析网关
    # port: 2375
    # protocol: http
publishers: # 制品发布配置
  s3: # S3发布凭证
    key: 1a2b3c4d5e6f # AWS访问密钥
    secret: 1a2b3c4d5e6f # AWS密钥

配置认证

Roger默认无认证，可通过自定义Passport.js认证模块启用：

1. 在config.yml中配置：

yaml
app:
  auth:
    provider: '/auth/myProvider.js'

2. 挂载认证模块：启动容器时添加-v /path/to/auth:/auth

3. myProvider.js需暴露注册认证机制的函数，示例参考https://github.com/namshi/roger/blob/master/examples/auth/local.js%E3%80%82

构建钩子

GitHub

配置GitHub Webhook以触发自动构建：

1. 进入仓库设置：https://github.com/YOU/YOUR_PROJECT/settings/hooks/new
2. 配置Payload URL为Roger地址（如http://your-roger-instance:8080/hooks/github）
3. 选择Content type为application/json
4. 触发事件选择Just the push event或根据需求选择
5. 保存后，推送代码、创建标签或在PR评论build please!将触发构建。

通知

GitHub状态通知

在构建完成后更新GitHub提交状态：

yaml
my-project:
  notify:
    - github

需确保GitHub用户对仓库有写权限。

Amazon SES邮件通知

通过Amazon SES发送邮件通知：

1. 项目配置（build.yml）：

yaml
my-project:
  notify:
    - emailSes

2. 服务器配置（config.yml）：

yaml
notifications:
  emailSes:
    accessKey: 1a2b3c4d5e6f
    secret: 1a2b3c4d5e6f
    region: eu-west-1
    to:
      - committer # 提交者邮箱
      - someone@yourcompany.com
    from: builds@company.com # 需在SES验证

Slack通知

构建完成后推送通知到Slack频道：

1. 项目配置（build.yml）：

yaml
my-project:
  notify:
    - slack

2. 服务器配置（config.yml）：

yaml
notifications:
  slack:
    global: 'true' # 全局启用
    channel: '#channel-name'
    icon_emoji: ':slack-emoji:'
    username: 'Roger'

发布制品

S3

将容器内文件发布到S3：

1. 项目配置（build.yml）：

yaml
myproject:
  publish:
    -
      to: s3
      copy: /src/build/public/ # 容器内路径
      bucket: my-bucket # S3桶
      bucketPath: initial-path # S3路径前缀
      command: gulp build # 发布前执行的命令

2. 服务器配置（config.yml）：

yaml
publishers:
  s3:
    key: 1a2b3c4d5e6f # AWS访问密钥
    secret: 1a2b3c4d5e6f # AWS密钥

使用不同构建和运行镜像

通过分离构建镜像和运行镜像减小最终镜像体积：

1. 项目配置（build.yml）：

yaml
myProject:
  build:
    dockerfile: Dockerfile.build # 构建镜像的Dockerfile
    extract: /src # 从构建镜像提取的目录

2. 构建镜像Dockerfile（Dockerfile.build）示例：

dockerfile
FROM node:latest

RUN apt-get update && apt-get install -y ruby-full build-essential
RUN gem install sass compass --no-ri --no-rdoc
RUN npm install -g gulp

COPY . /src
WORKDIR /src

RUN npm install && gulp sass # 构建操作

3. 运行镜像Dockerfile示例：

dockerfile
FROM alpine:edge

RUN apk add --update nodejs='=4.1.1-r0' && rm -rf /var/cache/apk/*

COPY . /src # 包含从构建镜像提取的/src内容
WORKDIR /src

EXPOSE 8080
CMD ["node", "src/app.js"]

钩子

after-build

构建完成后在容器内执行命令（如测试），失败则终止构建：

yaml
my-node-app:
  registry: registry.company.com
  after-build:
    - npm test

APIs

列出所有项目

GET /api/projects?limit=10（默认返回10个最近更新的项目）

响应示例：

json
{
  "projects": [
    {
      "name": "https://github.com/company/redis__redis-server",
      "alias": "redis-server (company/redis)",
      "latest_build": {
        "branch": "patch-1",
        "project": "https://github.com/company/redis__redis-server",
        "status": "passed",
        "id": "0715a3b5-43fe-4d07-9705-82641db07c25-redis-server",
        "tag": "registry.company.com/redis-server:patch-1",
        "created_at": "2015-07-02T08:44:28+00:00",
        "updated_at": "2015-07-02T08:45:09+00:00"
      }
    }
  ]
}

列出所有构建

GET /api/builds?limit=10（默认返回10个最近构建）

获取构建详情

GET /api/builds/BUILD_ID

响应示例：

json
{
  "build": {
    "branch": "patch-1",
    "project": "https://github.com/company/redis__redis",
    "status": "passed",
    "id": "0715a3b5-43fe-4d07-9705-82641db07c25-redis",
    "tag": "registry.company.com/redis:patch-1",
    "created_at": "2015-07-02T08:44:28+00:00",
    "updated_at": "2015-07-02T08:45:09+00:00"
  }
}

获取构建日志

GET /api/builds/BUILD_ID/log（流式返回构建日志）

触发构建

GET /api/v2/build?repo=REPO_URL&branch=BRANCH（默认分支为master）

示例：

• GET /api/build?repo=https://github.com/redis/redis
• GET /api/build?repo=https://github.com/redis/redis&branch=master

支持POST请求，可添加Docker构建选项： GET /api/build?repo=https://github.com/redis/redis&options[nocache]=true（禁用缓存）

生产环境使用

Roger已在Namshi生产环境稳定运行，支持所有容器的自动化构建。工程师推送代码后，Roger可在数秒内完成构建并推送至私有registry，适合企业内部CI/CD流程。

为什么选择Roger

Roger诞生于Docker早期，当时缺乏快速的Docker构建SaaS解决方案（Docker Hub构建需15分钟，Travis-CI等平台Docker集成不完善）。通过共享Docker socket在容器内运行，实现了秒级构建速度，同时提供灵活配置和集成能力，满足团队自动化构建需求。