From 7ec707ca4be5b153f45654be96ef7186be63bb08 Mon Sep 17 00:00:00 2001
From: Robert Collins <rbtcollins@hp.com>
Date: Thu, 5 Sep 2013 22:44:52 +1200
Subject: [PATCH] Improve Jenkins documentation.
The initial setup was not documented at all.
Change-Id: I074eabac958b77ecf3a333c9ea9beabd539b2f9e
---
doc/source/jenkins.rst | 57 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 56 insertions(+), 1 deletion(-)
diff --git a/doc/source/jenkins.rst b/doc/source/jenkins.rst
index 2bbfd8d8ad..1d56dca352 100644
--- a/doc/source/jenkins.rst
+++ b/doc/source/jenkins.rst
@@ -52,7 +52,7 @@ jobs:
* Minimal use of plugins: the more post-processing work that Jenkins
needs to perform on a job, the more likely we are to run into
compatibility problems among plugins, and contention for shared
- resources on the Jenkins master. A number of popuplar plugins
+ resources on the Jenkins master. A number of popular plugins
will cause all builds of a job to be serialized even if the jobs
otherwise run in parallel.
* Minimal build history: Jenkins stores build history in individual
@@ -92,3 +92,58 @@ based tests.
The :ref:`devstack-gate` project is used to maintain a pool of Jenkins
slaves that are used to run these tests. Devstack-gate jobs create
and delete Jenkins slaves as needed in order to maintain the pool.
+
+Sysadmin
+========
+
+Jenkins is largely hidden, and has no sensitive data exposed
+publically, so we use self-signed certs for Jenkins masters.
+
+After bringing up a jenkins node (16G memory instance if you use the
+stock jenkins.default) with puppet, log in and configure Jenkins by
+hand:
+
+#. Configure the site so it knows it's correct url.
+ (Jenkins URL in global config). This is needed to complete an SSO
+ sign-in.
+
+#. Configure the OpenID plugin for your SSO site (e.g. Launchpad)
+
+#. Do not set CSRF protection - that breaks Jenkins job builder.
+
+#. Login.
+
+#. Setup matrix security: add the 'authenticated' pseudo user and
+ grant Admin access to your own user.
+
+#. Setup one account per `http://ci.openstack.org/jenkins-job-builder/installation.html#configuration-file`
+ and grab the API token for it.
+
+#. Configure the number of executors you want on the Jenkins Master
+ (e.g. 1)
+
+#. Configure a maven environment (if you have Maven projects to test).
+
+#. Enable the gearman plugin globally. Your gearman server is
+ zuul.$project. If Test Connection fails, do a puppet run (puppet
+ agent --test) on the zuul machine, as gearman wouldn't have started
+ with no workers configured.
+
+#. Configure the timestamper plugin. E.g. to
+ '<b>'yyyy-MM-dd HH:mm:ss'</b> '
+
+#. Enable the zmq plugin globally if it is visible. No settings were
+ visible when writing this doc.
+
+#. You will configure global scp and ftp credentials for static and
+ docs sites respectively later, but as we haven't setup those sites
+ yet, thats not possible :).
+
+Puppet takes care of the rest.
+
+Quirks
+------
+
+Note that jenkins talks to it's slaves via ssh, the
+modules/openstack_project/manifests/init.pp file contains the ssh
+public key that puppet installs on the slaves.