blob: 77dee4a9071801af2089c6354b64658905dace31 [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001Quick Start Guide
2=================
3
4This provides a very simple overview of Zuul. It is recommended to
5read the following sections for more details.
6
7Install Zuul
8------------
9
10You can get zuul from pypi via::
11
12 pip install zuul
13
14Zuul Components
15---------------
16
17Zuul provides the following components:
18
19 - **zuul-scheduler**: The main Zuul process. Handles receiving
20 events, executing jobs, collecting results and posting reports.
21 Coordinates the work of the other components.
22
23 - **zuul-merger**: Scale-out component that performs git merge
24 operations. Zuul performs a large number of git operations in
25 the course of its work. Adding merger processes can help speed
26 Zuul's processing. This component is optional (zero or more of
27 these can be run).
28
29 - **zuul-executor**: Scale-out component for executing jobs. At
30 least one of these is required. Depending on system
31 configuration, you can expect a single executor to handle up to
32 about 100 simultaneous jobs. Can handle the functions of a
33 merger if dedicated mergers are not provided. One or more of
34 these must be run.
35
David Shrewsburyae734d12017-07-11 12:41:59 -040036 - **zuul-web**: A web server that currently provides websocket access to
37 live-streaming of logs.
38
James E. Blaireff5a9d2017-06-20 00:00:37 -070039 - **gearman**: optional builtin gearman daemon provided by zuul-scheduler
40
41External components:
42
43 - **gearman**: A gearman daemon if the built-in daemon is not used.
44
45 - **zookeeper**: A zookeeper cluster (or single host) for
46 communicating with Nodepool.
47
48 - **nodepool**: Provides nodes for Zuul to use when executing jobs.
49
50
51Zuul Setup
52----------
53
54At minimum you need to provide **zuul.conf** and **main.yaml** placed
55in **/etc/zuul/**. The following example uses the builtin gearman
56service in Zuul, and a connection to Gerrit.
57
58**zuul.conf**::
59
James E. Blair39840362017-06-23 20:34:02 +010060 [scheduler]
James E. Blaireff5a9d2017-06-20 00:00:37 -070061 tenant_config=/etc/zuul/main.yaml
62
63 [gearman_server]
64 start=true
65
66 [gearman]
67 server=127.0.0.1
68
69 [connection gerrit]
70 driver=gerrit
71 server=git.example.com
72 port=29418
73 baseurl=https://git.example.com/gerrit/
74 user=zuul
75 sshkey=/home/zuul/.ssh/id_rsa
76
77See :ref:`components` and :ref:`connections` for more details.
78
79The following tells Zuul to read its configuration from and operate on
80the *example-project* project:
81
82**main.yaml**::
83
84 - tenant:
85 name: example-tenant
86 source:
87 gerrit:
88 untrusted-projects:
89 - example-project
90
91Starting Zuul
92-------------
93
94You can run any zuul process with the **-d** option to make it not
95daemonize. It's a good idea at first to confirm there's no issues with
96your configuration.
97
98To start, simply run::
99
100 zuul-scheduler
101
102Once run you should have two zuul-scheduler processes (if using the
103built-in gearman server, or one process otherwise).
104
105Before Zuul can run any jobs, it needs to load its configuration, most
106of which is in the git repositories that Zuul operates on. Start an
107executor to allow zuul to do that::
108
109 zuul-executor
110
111Zuul should now be able to read its configuration from the configured
112repo and process any jobs defined therein.
113
114Troubleshooting
115---------------
116
117You can use telnet to connect to gearman to check which Zuul
118components are online::
119
120 telnet <gearman_ip> 4730
121
122Useful commands are **workers** and **status** which you can run by just
123typing those commands once connected to gearman.