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 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 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