--- url: /en/paas/system-runner.md --- ## Overview System administrators can add machines in the `Admin Management Platform` as Runners for `Cloud Native Build`/`Workspaces` functionality, available for users. CNB supports Linux, Mac, and Windows build machines. ### Two Hosting Modes For specific usage, see [Admin Configuration](#adding-runner-to-the-system) and [Runner Configuration](#configuration-process). #### System Hosting (Default) Machines managed by the CNB platform require mutual access between the machine and the platform. Added via `ip:port`. #### Self-Hosting Machines managed by users themselves only require direct access to the CNB platform. Added via a unique identifier. ## System Environment Requirements ### Linux Build Machines * TencentOS 3.2 / TencentOS 3.1 / CentOS 8 and derivatives * Kernel version 5.4+ recommended * docker >= 26.1.5 * Ports 8087 and 8088 must be available for listening ### Mac Build Machines * git >= 2.43.0 * Ports 8087 and 8088 must be available for listening Since Mac does not support `OverlayFS`, second-read cloning will degrade to normal cloning. ### Windows Build Machines * Recommended Windows 10 or above * git >= 2.43.0 * Ports 8087 and 8088 must be available for listening Since Windows does not support `OverlayFS`, second-read cloning will degrade to normal cloning. ## Configuration Process ### ==1. Configure Linux Build Machines (Standard Solution)== @[code-tree title="Initialize RUNNER Scripts" height="800px"](./system-runner) ### ==2. Configure Self-Hosted Build Machines=={.info} #### ==2.1=={.info} Create Self-Hosted RUNNER in Admin Console ::: note Tags must start with `cnb`. ::: ![Create Self-Hosted RUNNER](/images/system-runner/create-system-runner.en.png) ① Download the certificate from the Admin Console. ② Upload the certificate archive to the build machine configuration directory and extract it. * Linux: ==`/etc/orange-ci`== * Mac: ==`$HOME/orange-ci/etc/orange-ci`== * Windows: ==`C:/etc/orange-ci`== ③ The installation script will determine whether to enable TLS verification based on the presence of `orange-ci.pem`, `orange-runner.crt`, and `orange-runner.key` in the specified directory. #### ==2.2=={.info} Connect Self-Hosted RUNNER ::: note ① `CONNECTOR_ENDPOINT`: Make sure to confirm whether HTTPS is enabled and the current environment domain, e.g., wss://connector.yourdomain, and replace this variable in the setup script. ② `SELF_HOSTED_ID`: After completing step 2 in the Admin Console, you can obtain the unique identifier for this RUNNER. ③ Before running `.\orange-runner.exe start` or `orange-runner start`, you can use `.\orange-runner.exe` or `./orange-runner` to start the service and view error logs directly. ④ On Windows, if files are not found, disable hidden file extensions and verify they match expectations. ⑤ On Windows, file creation may have BOM header issues. Please check carefully. ::: ::: tabs @tab Linux 1. \==One-Click Setup Script== ```shell curl -fsSL https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/linux.sh | CONNECTOR_ENDPOINT=wss://connector.cnb.share.ralphlauren.cn SELF_HOSTED_ID=xxxx-xxxx-xxxx bash ``` 2. \==Configuration and Storage Directories== ```shell ① Certificate configuration directory: `/etc/orange-ci` ② RUNNER configuration file: `/etc/orange-ci/runner-config.json` ③ Data storage directory: `/data/orange-ci` ``` 3. \==Other Common Commands== ```shell # Install service orange-runner install # Start service orange-runner start # Stop service orange-runner stop # Uninstall service orange-runner uninstall # Remove global command rm /usr/local/bin/orange-runner # Check service running status orange-runner status # View logs tail -f /data/orange-runner/logs/app.log ``` @tab Mac 1. \==One-Click Setup Script== ```shell curl -fsSL https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/mac.sh | CONNECTOR_ENDPOINT=wss://connector.cnb.share.ralphlauren.cn SELF_HOSTED_ID=xxxx-xxxx-xxxx bash ``` 2. \==Configuration and Storage Directories== ```shell ① Certificate configuration directory: `$HOME/orange-ci/etc/orange-ci` ② RUNNER configuration file: `$HOME/orange-ci/etc/orange-ci/runner-config.json` ③ Data storage directory: `$HOME/orange-ci/data/orange-ci` ``` 2. \==Other Common Commands== ```shell # Install service orange-runner install # Start service orange-runner start # Stop service orange-runner stop # Uninstall service orange-runner uninstall # Remove global command rm /usr/local/bin/orange-runner # Check service running status orange-runner status # View logs tail -f /data/orange-runner/logs/app.log ``` @tab Windows 1. \==One-Click Setup Script== ```shell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Confirm:$False -Force ; invoke-webrequest https://docs.cnb.share.ralphlauren.cn/system-runner/scripts/windows.ps1 -outfile windows.ps1; $env:CONNECTOR_ENDPOINT='wss://connector.cnb.share.ralphlauren.cn'; $env:SELF_HOSTED_ID='xxxx-xxxx-xxxx'; ./windows.ps1 ``` 2. \==Configuration and Storage Directories== ```shell ① Certificate configuration directory: `C:/etc/orange-ci` ② RUNNER configuration file: `C:/etc/orange-ci/runner-config.json` ③ Data storage directory: `C:/data/orange-ci` ``` 3. \==Common Commands== ```shell # cd to the directory where orange-runner.exe is located cd $HOME\Downloads\orange-runner # Start service .\orange-runner.exe start # Stop service .\orange-runner.exe stop # Uninstall service .\orange-runner.exe uninstall # Delete exe file Remove-Item -Path .\orange-runner.exe # Check service running status .\orange-runner.exe status # View logs Get-Content 'C:\data\orange-runner\logs\app.log' -Wait -Tail 10 ``` ::: ## FAQ 1. When building multi-platform images with `docker buildx`, building ARM images fails with: `Error while loading /usr/sbin/dpkg-split: No such file or directory` Solution: ```bash docker run --rm --privileged multiarch/qemu-user-static --reset -p yes --credential yes ``` 1. `git clone` works on the host but times out in pipeline containers. Cause: IPv4 forwarding must be enabled. `cat /proc/sys/net/ipv4/ip_forward` should return `1`. If not enabled, edit with the following command: