blob: ae7d571de51dccca74e4bee693d1cf9e7682c25b [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001Installation
2============
3
4Install Zuul
5------------
6
7To install a Zuul release from PyPI, run::
8
9 pip install zuul
10
11Or from a git checkout, run::
12
13 pip install .
14
15That will also install Zuul's python dependencies. To minimize
16interaction with other python packages installed on a system, you may
17wish to install Zuul within a Python virtualenv.
18
19Zuul has several system-level dependencies as well. You can find a
20list of operating system packages in `bindep.txt` in Zuul's source
21directory.
22
23External Dependencies
24---------------------
25
26Zuul interacts with several other systems described below.
27
28Gearman
29~~~~~~~
30
31Gearman is a job distribution system that Zuul uses to communicate
32with its distributed components. The Zuul scheduler distributes work
David Shrewsbury1c61c712017-08-16 16:02:33 -040033to Zuul mergers and executors using Gearman. You may supply your own
James E. Blaireff5a9d2017-06-20 00:00:37 -070034gearman server, but the Zuul scheduler includes a built-in server
35which is recommended. Ensure that all Zuul hosts can communicate with
36the gearman server.
37
38Zuul distributes secrets to executors via gearman, so be sure to
39secure it with TLS and certificate authentication. Obtain (or
40generate) a certificate for both the server and the clients (they may
41use the same certificate or have individual certificates). They must
42be signed by a CA, but it can be your own CA.
43
44Nodepool
45~~~~~~~~
46
47In order to run all but the simplest jobs, Zuul uses a companion
48program, Nodepool, to supply the nodes (whether dynamic cloud
49instances or static hardware) used by jobs. Before starting Zuul,
50ensure you have Nodepool installed and any images you require built.
51Zuul only makes one requirement of these nodes: that it be able to log
52in given a username and ssh private key.
53
54.. TODO: SpamapS any zookeeper config recommendations?
55
56Nodepool uses Zookeeper to communicate internally among its
57components, and also to communicate with Zuul. You can run a simple
58single-node Zookeeper instance, or a multi-node cluster. Ensure that
David Shrewsbury1c61c712017-08-16 16:02:33 -040059the host running the Zuul scheduler has access to the cluster.
James E. Blaireff5a9d2017-06-20 00:00:37 -070060
61Ansible
62~~~~~~~
63
64Zuul uses Ansible to run jobs. Each version of Zuul is designed to
65work with a specific, contemporary version of Ansible. Zuul specifies
66that version of Ansible in its python package metadata, and normally
67the correct version will be installed automatically with Zuul.
68Because of the close integration of Zuul and Ansible, attempting to
69use other versions of Ansible with Zuul is not recommended.