Skip to content

Commit f38c4c9

Browse files
donny-dontdonny-dont
committed
Add buildbot-worker documentation
Create documentation on how to connect a `buildbot-worker` container to WebKit infrastructcure.
1 parent 9087bea commit f38c4c9

File tree

1 file changed

+120
-0
lines changed

1 file changed

+120
-0
lines changed

‎BUILDBOT.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Connecting a WebKit BuildBot
2+
The `docker-webkit-dev` project contains Docker images for running Buildbot
3+
workers that connect to WebKit infrastructure. The Windows WebKit port builds
4+
happen within Docker containers running the `webkitdev/buildbot-worker` image.
5+
6+
> [!IMPORTANT]
7+
> To connect to WebKit infrastructure credentials are required.
8+
> Contact the infrastructure team on [Slack](https://webkit.slack.com) for
9+
> access.
10+
11+
## Getting the image
12+
The `webkitdev/buildbot-worker` image is built and pushed to
13+
[Docker Hub](https://hub.docker.com/r/webkitdev/buildbot-worker). The following
14+
tags are supported. For the latest information on Windows container version
15+
compatibility see the
16+
[documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility)
17+
18+
| Tag Name | Automated | Description |
19+
|---|:---:|---|
20+
| 2022 | :white_check_mark: | A Windows 2022 server container |
21+
| windows-2022 | :x: | A Windows container, used for Layout Tests |
22+
| 1809 | :x: | A Windows 2019 server container |
23+
24+
Visit [Docker Hub](https://hub.docker.com/r/webkitdev/buildbot-worker/tags) to
25+
see when the last build happened for the image's tags.
26+
27+
## Configuring the Buildbot worker
28+
The `webkitdev/buildbot-worker` image uses environment variables for
29+
configuration. When invoking `docker run` environment variables are specified on
30+
the command line individually or through a file. See the
31+
[documentation](https://docs.docker.com/engine/reference/commandline/container_run/#env)
32+
for more details.
33+
34+
| Environment Variable | Required | Description |
35+
|---|:---:|---|
36+
| BUILD_HOST_NAME | :white_check_mark: | Host of the buildbot instance, either `build.webkit.org` or `ews-build.webkit.org` |
37+
| BUILD_HOST_PORT | :x: | Port of the buildbot instance, defaults to 17000 |
38+
| BUILD_WORKER_NAME | :white_check_mark: | Name for the worker, provided by infrastructure team |
39+
| BUILD_WORKER_PASSWORD | :white_check_mark: | Password for the worker, provided by infrastructure team |
40+
| BUILD_WORKER_KEEPALIVE | :x: | Time in seconds that messages should be sent by the worker to the server, defaults to 240 |
41+
| ADMIN_NAME | :x:| Contact name for the admin of the worker |
42+
| ADMIN_EMAIL | :x: | Contact e-mail address for the admin of the worker |
43+
| HOST_DESCRIPTION |:x: | A description of the host running the worker |
44+
| COMPILER | :x: | Set this to `Clang` to use `clang-cl`, defaults to `cl` |
45+
46+
The preferred method of setup uses an environment file. An example file to fill
47+
out with all the options present looks like this. Save the text file locally
48+
with the name corresponding to worker name; for this example `build.env` is
49+
used.
50+
51+
```txt
52+
ADMIN_EMAIL=<email>
53+
ADMIN_NAME=<admin>
54+
BUILD_HOST_NAME=<host>
55+
BUILD_WORKER_NAME=<name>
56+
BUILD_WORKER_PASSWORD=<password>
57+
HOST_DESCRIPTION=<description>
58+
COMPILER=Clang
59+
```
60+
61+
## Running the Buildbot worker
62+
On a Windows Server 2022 machine run the following in a powershell session. On
63+
Windows Server 2022 the Docker container runs in process isolation mode which
64+
gives it access to all the resources of the host.
65+
66+
```powershell
67+
docker run --name build --env-file build.env --detach --restart always webkitdev/buildbot-worker:2022
68+
```
69+
70+
On a Windows 11 machine run the following in a powershell session. On Windows 11
71+
the Docker container runs in Hyper-V isolation mode so the amount of resources
72+
need to be specified with `cpu-count` and `memory`. Replace `X` with the number
73+
of processors to use and `Y` with the amount of memory in GBs to reserve for the
74+
container.
75+
76+
```powershell
77+
docker run --name build --env-file build.env --detach --restart always --cpu-count X --memory Yg webkitdev/buildbot-worker:2022
78+
```
79+
80+
To see if the container is running invoke the following in a powershell session.
81+
If everything is configured the output will look like this. Check the Buildbot
82+
instance and the worker should be present in its listing.
83+
84+
```powershell
85+
docker logs build
86+
87+
Buildbot information
88+
Name: <name>
89+
Admin: <admin> <email>
90+
Description: <description>
91+
Host system
92+
Processors: 1
93+
Logical processors: 16
94+
Total Physical Memory: 24.50gb
95+
\\60A8A235F96C\root\cimv2:Win32_LogicalDisk.DeviceID="C:"
96+
Disk information C:
97+
Total Disk Space: 126.87gb
98+
Available Disk Space: 126.74gb
99+
Initializing Visual Studio environment
100+
**********************************************************************
101+
** Visual Studio 2022 Developer Command Prompt v17.8.5
102+
** Copyright (c) 2022 Microsoft Corporation
103+
**********************************************************************
104+
[vcvarsall.bat] Environment initialized for: 'x64'
105+
Found compiler at C:\LLVM\bin\clang-cl.exe
106+
Initializing buildbot configuration
107+
Looking in C:\BW\Scripts for additional startup scripts
108+
0 scripts found
109+
Starting buildbot
110+
buildbot-worker start
111+
```
112+
113+
## Debugging
114+
To check on what is going on inside the container and diagnose an issue open a
115+
command prompt on the machine running the Docker container and enter the
116+
following command to get an interactive Powershell prompt within it.
117+
118+
```powershell
119+
docker exec -it build powershell
120+
```

0 commit comments

Comments
 (0)