James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 1 | Quick Start Guide |
| 2 | ================= |
| 3 | |
| 4 | This provides a very simple overview of Zuul. It is recommended to |
| 5 | read the following sections for more details. |
| 6 | |
| 7 | Install Zuul |
| 8 | ------------ |
| 9 | |
| 10 | You can get zuul from pypi via:: |
| 11 | |
| 12 | pip install zuul |
| 13 | |
| 14 | Zuul Components |
| 15 | --------------- |
| 16 | |
| 17 | Zuul 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 Shrewsbury | ae734d1 | 2017-07-11 12:41:59 -0400 | [diff] [blame] | 36 | - **zuul-web**: A web server that currently provides websocket access to |
| 37 | live-streaming of logs. |
| 38 | |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 39 | - **gearman**: optional builtin gearman daemon provided by zuul-scheduler |
| 40 | |
| 41 | External 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 | |
| 51 | Zuul Setup |
| 52 | ---------- |
| 53 | |
| 54 | At minimum you need to provide **zuul.conf** and **main.yaml** placed |
| 55 | in **/etc/zuul/**. The following example uses the builtin gearman |
| 56 | service in Zuul, and a connection to Gerrit. |
| 57 | |
| 58 | **zuul.conf**:: |
| 59 | |
James E. Blair | 3984036 | 2017-06-23 20:34:02 +0100 | [diff] [blame] | 60 | [scheduler] |
James E. Blair | eff5a9d | 2017-06-20 00:00:37 -0700 | [diff] [blame] | 61 | 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 | |
| 77 | See :ref:`components` and :ref:`connections` for more details. |
| 78 | |
| 79 | The following tells Zuul to read its configuration from and operate on |
| 80 | the *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 | |
| 91 | Starting Zuul |
| 92 | ------------- |
| 93 | |
| 94 | You can run any zuul process with the **-d** option to make it not |
| 95 | daemonize. It's a good idea at first to confirm there's no issues with |
| 96 | your configuration. |
| 97 | |
| 98 | To start, simply run:: |
| 99 | |
| 100 | zuul-scheduler |
| 101 | |
| 102 | Once run you should have two zuul-scheduler processes (if using the |
| 103 | built-in gearman server, or one process otherwise). |
| 104 | |
| 105 | Before Zuul can run any jobs, it needs to load its configuration, most |
| 106 | of which is in the git repositories that Zuul operates on. Start an |
| 107 | executor to allow zuul to do that:: |
| 108 | |
| 109 | zuul-executor |
| 110 | |
| 111 | Zuul should now be able to read its configuration from the configured |
| 112 | repo and process any jobs defined therein. |
| 113 | |
| 114 | Troubleshooting |
| 115 | --------------- |
| 116 | |
| 117 | You can use telnet to connect to gearman to check which Zuul |
| 118 | components are online:: |
| 119 | |
| 120 | telnet <gearman_ip> 4730 |
| 121 | |
| 122 | Useful commands are **workers** and **status** which you can run by just |
| 123 | typing those commands once connected to gearman. |