Add quick-start guide
Change-Id: I718b2dd6fc6c71f67fbb1774ae4b0b625fdf053d
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 61f9e4f..3c793da 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,6 +13,7 @@
.. toctree::
:maxdepth: 2
+ quick-start
gating
connections
triggers
diff --git a/doc/source/quick-start.rst b/doc/source/quick-start.rst
new file mode 100644
index 0000000..82779c6
--- /dev/null
+++ b/doc/source/quick-start.rst
@@ -0,0 +1,162 @@
+Quick Start Guide
+=================
+
+System Requirements
+-------------------
+
+For most deployments zuul only needs 1-2GB. OpenStack uses a 30GB setup.
+
+Install Zuul
+------------
+
+You can get zuul from pypi via::
+
+ pip install zuul
+
+Zuul Components
+---------------
+
+Zuul provides the following components:
+
+ - **zuul-server**: scheduler daemon which communicates with Gerrit and
+ Gearman. Handles receiving events, launching jobs, collecting results
+ and postingreports.
+ - **zuul-merger**: speculative-merger which communicates with Gearman.
+ Prepares Git repositories for jobs to test against. This additionally
+ requires a web server hosting the Git repositories which can be cloned
+ by the jobs.
+ - **zuul-cloner**: client side script used to setup job workspace. It is
+ used to clone the repositories prepared by the zuul-merger described
+ previously.
+ - **gearmand**: optional builtin gearman daemon provided by zuul-server
+
+External components:
+
+ - Jenkins Gearman plugin: Used by Jenkins to connect to Gearman
+
+Zuul Communication
+------------------
+
+All the Zuul components communicate with each other using Gearman. As well as
+the following communication channels:
+
+zuul-server:
+
+ - Gerrit
+ - Gearman Daemon
+
+zuul-merger:
+
+ - Gerrit
+ - Gearman Daemon
+
+zuul-cloner:
+
+ - http hosted zuul-merger git repos
+
+Jenkins:
+
+ - Gearman Daemon via Jenkins Gearman Plugin
+
+Zuul Setup
+----------
+
+At minimum we need to provide **zuul.conf** and **layout.yaml** and placed
+in /etc/zuul/ directory. You will also need a zuul user and ssh key for the
+zuul user in Gerrit. The following example uses the builtin gearmand service
+in zuul.
+
+**zuul.conf**::
+
+ [zuul]
+ layout_config=/etc/zuul/layout.yaml
+
+ [merger]
+ git_dir=/git
+ zuul_url=http://zuul.example.com/p
+
+ [gearman_server]
+ start=true
+
+ [gearman]
+ server=127.0.0.1
+
+ [connection gerrit]
+ driver=gerrit
+ server=git.example.com
+ port=29418
+ baseurl=https://git.example.com/gerrit/
+ user=zuul
+ sshkey=/home/zuul/.ssh/id_rsa
+
+See :doc:`zuul` for more details.
+
+The following sets up a basic timer triggered job using zuul.
+
+**layout.yaml**::
+
+ pipelines:
+ - name: periodic
+ source: gerrit
+ manager: IndependentPipelineManager
+ trigger:
+ timer:
+ - time: '0 * * * *'
+
+ projects:
+ - name: aproject
+ periodic:
+ - aproject-periodic-build
+
+Starting Zuul
+-------------
+
+You can run zuul-server with the **-d** option to make it not daemonize. It's
+a good idea at first to confirm there's no issues with your configuration.
+
+Simply run::
+
+ zuul-server
+
+Once run you should have 2 zuul-server processes::
+
+ zuul 12102 1 0 Jan21 ? 00:15:45 /home/zuul/zuulvenv/bin/python /home/zuul/zuulvenv/bin/zuul-server -d
+ zuul 12107 12102 0 Jan21 ? 00:00:01 /home/zuul/zuulvenv/bin/python /home/zuul/zuulvenv/bin/zuul-server -d
+
+Note: In this example zuul was installed in a virtualenv.
+
+The 2nd zuul-server process is gearmand running if you are using the builtin
+gearmand server, otherwise there will only be 1 process.
+
+Zuul won't actually process your Job queue however unless you also have a
+zuul-merger process running.
+
+Simply run::
+
+ zuul-merger
+
+Zuul should now be able to process your periodic job as configured above once
+the Jenkins side of things is configured.
+
+Jenkins Setup
+-------------
+
+Install the Jenkins Gearman Plugin via Jenkins Plugin management interface.
+Then naviage to **Manage > Configuration > Gearman** and setup the Jenkins
+server hostname/ip and port to connect to gearman.
+
+At this point gearman should be running your Jenkins jobs.
+
+Troubleshooting
+---------------
+
+Checking Gearman function registration (jobs). You can use telnet to connect
+to gearman to check that Jenkins is registering your configured jobs in
+gearman::
+
+ telnet <gearman_ip> 4730
+
+Useful commands are **workers** and **status** which you can run by just
+typing those commands once connected to gearman. Every job in your Jenkins
+master must appear when you run **workers** for Zuul to be able to run jobs
+against your Jenkins instance.