## page was renamed from JenkinsSetup
= Setting up Jenkins and a Jenkins instance =

Jenkins is our continuous build system. That is, it can be configured to check out code from our SVN (either on request on the Jenkins website or automatically when a a file in the repository changes), and test it. Our typical use case is our standard Makefile or build.xml file with the standard targets ''build'' (for compiling the code), ''test'' (for running the unit tests), ''checkstyle'' (for checking the style), and ''clean'' (clean up all non-source files).

== Installing Jenkins ==

Please create ''official'' instances only on [[http://ad-jenkins.informatik.privat|ad-jenkins.informatik.privat]]!

=== Prerequisites ===

 * Java for jenkins (already installed on ad-jenkins)
 * A name for the instance, denoted as <instance> in the following guide. Please ''use lowercase only''.
 * A port for the instance (<port>)
 * A user to run the instance as ''jenkins'' and '''not as''' your user!

=== Installing ===

Download Jenkins from https://jenkins.io, please ''use the LTS Release''.

{{{
wget http://mirrors.jenkins.io/war-stable/latest/jenkins.war
}}}

Create a systemd unit to start/stop the new instance at {{{/etc/systemd/system/jenkins_<instance>.service}}}.
{{{
[Unit]
Description=Jenkins <instance> Daemon

[Service]
Environment="JENKINS_HOME=/local/jenkins/<instance>/"
ExecStart=/usr/bin/java -jar /local/jenkins/<instance>/jenkins.war --httpPort=<port>
User=jenkins

[Install]
WantedBy=multi-user.target
}}}

The unit used for the ''completesearch'' instance looks as follows:

{{{
[Unit]
Description=Jenkins completesearch Daemon

[Service]
Environment="JENKINS_HOME=/local/jenkins/completesearch/"
ExecStart=/usr/bin/java -jar /local/jenkins/completesearch/jenkins.war --httpPort=8081
User=jenkins

[Install]
WantedBy=multi-user.target
}}}

Reload systemd {{{systemctl daemon-reload}}} and start the instance {{{systemctl start jenkins_<instance>.service}}}. Autostart should be enabled with  {{{systemctl enable jenkins_<instance>.service}}}.

== Setting up a Jenkins instance ==

=== Prerequisites ===

 * Install required system packages for the software to be build [[https://ad-wiki.informatik.uni-freiburg.de/completesearch/QuickIntro|e.g. CompleteSearch]].
 * Determine what jenkins shall do/test in this instance.

=== Initial configuration ===

==== Setup jenkins ====

Unlock the running jenkins (found at {{{<host>:<port>}}}) using the password in {{{/local/jenkins/<instance>/secrets/initialAdminPassword}}}.

Choose "Select plugins to install" and for ''completesearch'' only use:
 * OWASP Markup Formatter Plugin
 * Credentials Binding Plugin
 * Checkstyle Plug-in
 * Cobertura Plugin
 * Warnings Plug-in
 * Subversion Plug-in
 * Matrix Authorization Strategy Plugin
 * Email Extension Plugin
 * Mailer Plugin

Create initial account, please use the ''TF-Account'' here.
 
==== Configure jenkins ====

Goto {{{/configureSecurity/}}} and select matrix-based, add the admin user and grant all permissions. Grant general read and job read/workspace to Anonymous if the jobs shall be accessable to everyone. If finer permissions are needed, use job-based-matrix but still grant the admin user global permissions.

Goto {{{/pluginManager/}}} and install additional plugins for ''completesearch'' these are:
 * Static Analysis Collector Plug-in
 * Violations plugin

Goto {{{/configure}}} and set ''E-Mail address'' for sending, {{{Jenkins <ad-svn-noreply@informatik.uni-freiburg.de>}}} is used currently. Please change the ''jenkins url'' if it does not fit, e.g. behind a reverse proxy.

== Setting up a Jenkins job ==

Goto {{{/newJob}}} and create a new ''Free Style''-Job and select ''Subversion'' as Source-Code-Management with {{{https://ad-svn.informatik.uni-freiburg.de/completesearch/codebase}}} as the repository url. If no valid credentials are found, please add them. '''''TODO: could ad-jenkins get read-only for all?'''''

Add a shell build step
{{{
make "CXX_DEBUG=-O3 -g" "CS_CODE_DIR=$WORKSPACE" clean-all build-all test-all
make "CS_CODE_DIR=$WORKSPACE" -C example/xml/ test-pall-xml
make "CS_CODE_DIR=$WORKSPACE" -C example/csv/ test-pall-csv
./gcovr -x -r . > coverage.xml
python utility/cpplint.py */*.cpp */*.h &> cpplint.xml || echo 0
}}}

Add post build steps as required for the job. For ''completesearch'' these are:
 * Static code analysis
 * JUnit
 * Editable Email Notification