Cài đặt CircleCI trên Windows, macOS, Linux, Docker, Kubernetes

1. Tổng quan

CircleCI Runner là thành phần cho phép bạn chạy job trên hạ tầng riêng, tương tự Jenkins Agent. CircleCI Cloud chịu trách nhiệm điều phối workflow, còn Runner chỉ tập trung thực thi.

CircleCI Cloud: UI, pipeline orchestration, log & artifact.
Self-Hosted Runner: chạy on-premise / VM / container / Kubernetes.

Runner phù hợp cho workload yêu cầu bảo mật, build Docker nặng, GPU, hoặc môi trường đặc thù mà CircleCI cloud không hỗ trợ.

2. Prerequisites

Yêu cầu hệ thống

Resource Class Token (lấy tại CircleCI => Project => Settings => Runner => Inventory).
Đã tạo namespace cho runner.

Phần cứng

Tối thiểu: 1 vCPU, 2GB RAM
Khuyến nghị: 2 vCPU+, 4–8GB RAM nếu chạy Docker build hoặc test nhiều dependency.

3. Cài đặt CircleCI Runner bằng Docker

3.1 Docker Compose

version: '3.8'

services:
  circleci-runner:
    image: circleci/runner:launch-agent
    container_name: circleci-runner
    restart: unless-stopped
    environment:
      - CIRCLECI_RESOURCE_CLASS=my-namespace/my-docker-runner
      - CIRCLECI_API_TOKEN=your-runner-token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - ci-net

networks:
  ci-net:

Lưu ý bảo mật:
Mount docker.sock cho phép runner có toàn quyền root trên host. Nếu dùng trong production, cần hạn chế quyền hoặc chạy runner trong máy ảo tách biệt.

3.2 Khởi chạy

docker-compose up -d
docker logs -f circleci-runner

Runner sẽ tự kết nối outbound lên CircleCI Cloud.

4. Cài đặt Runner trên Windows

4.1 Các bước

Tải binary Launch Agent dành cho Windows.
Tạo thư mục:
```
C:\Program Files\CircleCI Runner
```
Tạo file:
```
launch-agent-config.yaml
```

Ví dụ:

runner:
  name: "windows-node"
  token: "your-token"
  resource_class: "namespace/windows"
  mode: single-task

Cài đặt service (NSSM hoặc Windows Service).
Khởi chạy Runner.

Logs có thể xem tại Event Viewer.

4.2 Lưu ý

Cần cài Git, MSBuild, Chocolatey trước.
Job Windows thường dùng shell: powershell.exe hoặc cmd.exe.

5. Cài đặt trên macOS

5.1 Cài đặt

curl -fLSs https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent/release/latest/circleci-launch-agent-darwin-amd64 > circleci-launch-agent
chmod +x circleci-launch-agent

5.2 Quản lý

Chạy thủ công:

./circleci-launch-agent --config launch-agent-config.yaml

Nếu muốn chạy background => tạo Launchd service.

6. Cài đặt Runner trên Linux

6.1 Ubuntu/Debian

curl -fLSs https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent/release/latest/circleci-launch-agent-linux-amd64 > circleci-launch-agent
chmod +x circleci-launch-agent
sudo mv circleci-launch-agent /usr/local/bin/

Tạo user:

sudo useradd --comment 'CircleCI Runner' --create-home circleci
sudo mkdir -p /etc/circleci-runner
sudo chown -R circleci: /etc/circleci-runner

Thêm systemd service:

[Unit]
Description=CircleCI Runner
After=network.target

[Service]
User=circleci
ExecStart=/usr/local/bin/circleci-launch-agent --config /etc/circleci-runner/launch-agent-config.yaml
Restart=always

[Install]
WantedBy=multi-user.target

6.2 RHEL / CentOS / Rocky

sudo dnf install git -y
curl -fLSs https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent/release/latest/circleci-launch-agent-linux-amd64 > circleci-launch-agent
sudo chmod +x circleci-launch-agent
sudo mv circleci-launch-agent /bin/

7. Triển khai CircleCI Runner trên Kubernetes

circleci-k8s.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: circleci
---
apiVersion: v1
kind: Secret
metadata:
  name: circleci-runner-secret
  namespace: circleci
stringData:
  CIRCLECI_API_TOKEN: "your-token-here"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: circleci-runner
  namespace: circleci
spec:
  replicas: 1
  selector:
    matchLabels:
      app: circleci-runner
  template:
    metadata:
      labels:
        app: circleci-runner
    spec:
      containers:
      - name: runner
        image: circleci/runner:launch-agent
        env:
        - name: CIRCLECI_RESOURCE_CLASS
          value: "my-namespace/k8s-runner"
        - name: CIRCLECI_API_TOKEN
          valueFrom:
            secretKeyRef:
              name: circleci-runner-secret
              key: CIRCLECI_API_TOKEN
        resources:
          requests:
            cpu: 500m
            memory: 512Mi

Lưu ý quan trọng:
CircleCI Runner trên Kubernetes không tự build Docker nếu không có Docker-in-Docker hoặc buildkit sidecar.

8. Nginx caching proxy

CircleCI Runner không có giao diện web, nên Reverse Proxy là không cần thiết. Tuy nhiên, bạn có thể dùng Nginx làm caching proxy để tăng tốc tải dependency (npm, pip…).

server {
    listen 8080;
    server_name cache.local;

    location / {
        proxy_pass https://registry.npmjs.org;
        proxy_set_header Host registry.npmjs.org;

        proxy_cache my_cache;
        proxy_cache_valid 200 1d;
        proxy_ignore_headers Set-Cookie;
    }
}

9. Executor Types

9.1 Machine Runner

Chạy trực tiếp trên OS.
Dùng cho workload GPU, privileged, kernel-level, hoặc build Docker nặng.

9.2 Container Runner

Mỗi job chạy trong container mới.
Clean, reproducible, dễ scale.

10. Post-Installation Checklist

Kiểm tra runner tại CircleCI => Inventory => Runners
Tạo .circleci/config.yml
Khớp resource_class với runner
Push pipeline đầu tiên để validate

Ví dụ cấu hình:

jobs:
  build:
    machine: true
    resource_class: my-namespace/my-runner
    steps:
      - checkout
      - run: echo "Running on self-hosted CircleCI Runner"