Support free tutorials



vogella training Training Books

Continuous Integration with Jenkins - Tutorial

Lars Vogel

Version 1.4

05.06.2015

Jenkins

This article describes how to build a continuous integration cycle for Java development with the Jenkins continuous integration build server.


Table of Contents

1. Continuous Integration with Jenkins
1.1. Continuous Integration Overview
1.2. What is the Jenkins integration server?
1.3. Jenkins and extensibility
2. Installation
2.1. Installing Jenkins on Ubuntu
2.2. Using native packages on other platforms
2.3. Using the .WAR file of Jenkins
3. Apache Ant, Tomcat
4. Configure Jenkins
4.1. Entering the JDK and your build system
4.2. Secure Jenkins
5. Jenkins management
5.1. Plug-in management
5.2. Restart your Jenkins
6. Support for the Git version control systems
7. Setting up a Jenkins job
8. Prerequisites for build Android apps with Jenkins
9. How to build your Android application with Jenkins
9.1. Overview
9.2. Android Jenkins build job prerequisites
9.3. Installation of the Android SDK
9.4. Jenkins Plug-ins for installation
9.5. Running an Android build with Jenkins
9.6. Other useful plug-ins
10. Jenkins backup and copying files
10.1. Jenkins backup and copying files
10.2. Managing Jenkins with Git
11. About this website
12. Links and Literature
12.1. Jenkins links
12.2. vogella GmbH training and consulting support

1. Continuous Integration with Jenkins

1.1. Continuous Integration Overview

Continuous integration is a process in which all development work is integrated at a predefined time or event and the resulting work is automatically tested and built. The idea is that development errors are identified very early in the process.

1.2. What is the Jenkins integration server?

Jenkins is one open source tool to perform continuous integration. The basic functionality of Jenkins is to execute a predefined list of steps based on a certain trigger.

The trigger might for example be an change in a version control system or a time based trigger, e.g., a build every 20 minutes.

The list of steps can for example include:

  • perform a software build with Apache Maven or Gradle

  • Run a shell script

  • Archive the build result

  • Afterwards start the integration tests

Jenkins also monitors the execution of the steps and allows to stop the process if one of the steps fails. Jenkins allows to notify users about the build success or failure.

Jenkins can be started via the command line or can run in a web application server. Under Linux you can also install Jenkins as a system service.

1.3. Jenkins and extensibility

Jenkins can be extended by additional plug-ins, e.g., for building and testing Android applications or to support the Git version control system.

2. Installation

2.1. Installing Jenkins on Ubuntu

Jenkins provides Debian/Ubuntu packages which install Jenkins and register Jenkins as start service. See the following URL for details.

http://pkg.jenkins-ci.org/debian/ 

Jenkins stores all the settings, logs and build artifacts in its home directory. The default installation directory is /var/lib/jenkins under Ubuntu.

This creates a /etc/init.d/jenkins start script which starts Jenkins automatically at boot time.

If you start it locally, you find it running under the following URL: http://localhost:8080/

2.2. Using native packages on other platforms

For most platforms you have native packages, see the Jenkins Homepage.

2.3. Using the .WAR file of Jenkins

Download the jenkins.war file from Jenkins Homepage.

You can also start Jenkins directly via the command line with java -jar jenkins*.war. If you start it locally, you find it running under the following URL: http://localhost:8080/

To run it in your Tomcat server, put the .WAR file into the webapps directory. If you start Tomcat, your Jenkins installation will be available under http://localhost:8080/jenkins

Note

If the jenkins.war is deployed in your webapps directory, but cannot be started and the tomcat manager says FAIL - Application at context path /jenkins could not be started , you may need to grant the permissons for JENKINS_HOME.

cd /usr/share/tomcat7
            sudo mkdir .jenkins
            sudo
            chown tomcat7:nogroup .jenkins 

This makes the .jenkins folder writable and Jenkins can use it.

3. Apache Ant, Tomcat

If you want to install Jenkins in a web container, you can use, for example, Tomcat or Jetty. See the Apache Tomcat Tutorial.

In this example we use Apache Maven to build a simple Java project. Please see the Apache Maven tutorial for details.

We use Git in this example. Please see the Git tutorial for details.

4. Configure Jenkins

4.1. Entering the JDK and your build system

Before using Jenkins you need to tell it where your JDK and ant installation is. Open Jenkins in your browser and click Manage Jenkins and then Configure System.

Jenkins at first startup

Enter the correct path to your JDK, Apache Ant and Maven and press the Save button below. Jenkins can also install these for your automatically.

Configuring Jenkins

4.2. Secure Jenkins

It is recommended to secure Jenkins. Manage Jenkins and then Configure Global Security. Select the Enable security flag. The easiest way is to use Jenkins own user database. Create at least the user "Anonymous" with read access. Also create entries for the users you want to add in the next step.

Access restrictions

On the login page, select Create an account to create the users you just gave access.

Create Jenkins account

Sign up a new Jenkins user

Go to Manage Jenkins, Manage and Assign Roles and then Assign Roles to grant the newly created user additional access rights.

Sign up a new Jenkins user

Navigate to Manage Roles to define access restrictions in detail. Pattern is a regex value of the job name. The following grants unregistered users read-only access to your build jobs that start with the C-MASTER or M-MASTER prefix and only those.

Sign up a new Jenkins user

5. Jenkins management

5.1. Plug-in management

Jenkins can be extended via additional plug-ins with more functionality. You can configure your plug-ins via the Manage JenkinsManager Plugins link.

To install plugins in Jenkins select use the Manage JenkinsManager Plugins link and search for the plugin you want to install. Select it from the list and select to install it and restart Jenkins.

The following table is a summary of commonly used plug-ins.

Table 1. Jenkins plug-ins

Plug-in name Description URL
Git Plugin This plugin allows use of Git as a build SCM. https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin
Xvnc plugin

This plugin allows projects to run xvnc during a build. This allows for example to run tests which requires a display to run on a virtual display. To use this plug-in you need to connect once to your vncserver on the command line to provide a password. Use for example the following commands.

# install vncserver
apt-get install vnc4server

# switch to jenkins user
sudo su jenkins

# connect to vncserver which creates the password
vncserver :10 

wiki.jenkins-ci.org/display/JENKINS/Xvnc+Plugin
Gradle Plugin

This plugin allows to run Gradle builds, e.g., as required for Android, via Jenkins.

https://wiki.jenkins-ci.org/display/JENKINS/Gradle+Plugin
Maven Plugin

This plugin allows to run Maven builds.

https://wiki.jenkins-ci.org/display/JENKINS/Maven+Project+Plugin


5.2. Restart your Jenkins

You can manually restart Jenkins by adding restart as URL parameter.

How to manually restart Jenkins

6. Support for the Git version control systems

Jenkins supports the Git version control system via a plugin. Select the Manage JenkinsManager Plugins link. Here you have to install the Git Plugin.

To clone a Git repostory via Jenkins you need to enter the email and user name for your Jenkins system. For this switch into your job directory and run the git config command.

# Need to configure the Git email and user for the Jenkins job

# switch to the job directory
cd /var/lib/jenkins/jobs/Android/workspace

# setup name and email
sudo git config user.name "jenkins"
sudo git config user.email "test@gmail.com" 

7. Setting up a Jenkins job

The build of a project is handled via jobs in Jenkins. Select New Item from the menu

Setting up a Jenkins job

Afterwards enter a name for the job and select Freestyle Job. Press OK to create a new Job in Jenkins.

The next page allows you to configure your job. If you for example using Git, enter the URL to the Git repository. If the repository is not public, you may also need to configure the credentials.

Setting up a Jenkins job

Specify when and how your build should be triggered. The following example polls the Git repository every 15 min and triggers a build, if something has changed in the repo.

Setting up a Jenkins job

I typically delete the workspace before a build to avoid any side-effect. In the Build section you can add a build step, e.g., a Maven build.

Setting up a Jenkins job

Press Save to finish the job definition. Press Build Now on the job page to validate the job works as expected.

Setting up a Jenkins job

After a while the job should go to green or blue (depending on your configuration), if successful. Click on the job and afterwards on Console Output to see the log file in case of an error or to validate that log looks as expected.

Setting up a Jenkins job

8. Prerequisites for build Android apps with Jenkins

The following descriptions for build Android applications with Jenkins assume that you have already a correct Gradle build file for your Android application. See Android build tutorial.

9. How to build your Android application with Jenkins

9.1. Overview

Jenkins supports the automatic building and testing of Android applications.

9.2. Android Jenkins build job prerequisites

To create a build job on Jenkins you need to have a working build setup. The Android tooling generates automatically a valid Gradle build file.

9.3. Installation of the Android SDK

The Android SDk must be available on the server. If you build server has no display server you need to install the Android SDK from the command line. You also need to configure the location for the Android SKD for Jenkins.

# download the Android SDK via wget
# for the correct URL see http://developer.android.com/sdk/index.html
# and look in the section "SDK Tools Only"
wget <link from the above website>
# example
# wget http://dl.google.com/android/android-sdk_r24.2-linux.tgz
# unpack it
tar zxvf filename

# Add the new directory to your patch
# assumes you exported it to /opt/
# this must be set for the Jenkins user
export ANDROID_HOME="/opt/android-sdk-linux"
export PATH="$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$PATH"

// run this as Jenkins user
android update sdk --no-ui 

Use android list targets to see what ABIs are installed. If no are listed manual install one.

9.4. Jenkins Plug-ins for installation

You need the follwing plug-ins to build Android application with Jenkins:

  • Gradle Plugin

  • Git Plugin - if Git is used for the project sources

  • Android Emulator Plugin - supporting starting and unlocking an Android emulator and blocks the build until the emulator has started. Required for running tests. A detailed description of this plugin can be found under the following URL: Android Emulator Plugin Jenkins page.

9.5. Running an Android build with Jenkins

To create an Android build job on Jenkins, select New Job, enter a job name and select the Build a free-style software project option.

Create new Jenkins job

You configure from where the source should be cloned.

Create new Jenkins job

You configure the emulator which should be started. Ensure that you do not select the Show emulator window option, as your build server should not depend on the availability of a display server.

Android emulator settings Jenk

Add a Gradle build step to your Jenkins jobs.

Apache Ant build file for Jenkins Android build

9.6. Other useful plug-ins

The Android Emulator Plugin supports a new job with the Build multi-configuration project option. This option allows you to test multiple emulator configurations at the same time. You can, for example, test different languages, densities, screen resolutions, etc. Typically you have two Jobs, one for a simple build and test run and a multi-configuration project to test the build on different device configurations.

You can combine Android Emulator Plugin with the Amazon-EC2-Plug-in to run the build and theJenk tests on several machines simultaneously.

Another useful plug-in is the Lint plug-in which allows to run your Lint checks via Jenkins. See Lint Plug-in for details.

10. Jenkins backup and copying files

10.1. Jenkins backup and copying files

Jenkins stores all the settings, logs and build artifacts in its home directory, for example, in /var/lib/jenkins under the default install location of Ubuntu.

To create a backup of your Jenkins setup, just copy this directory.

The jobs directory contains the individual jobs configured in the Jenkins install. You can move a job from one Jenkins installation to another by copying the corresponding job directory. You can also copy a job directory to clone a job or rename the directory.

Click reload config button in the Jenkins web user interface to force Jenkins to reload configuration from the disk.

See Adminstration of Jenkins for details.

10.2. Managing Jenkins with Git

Jenkins supports the https://wiki.jenkins-ci.org/display/JENKINS/SCM+Sync+configuration+plugin plug-in which allows you to store every change in a Git repo.

It is also possible to manually maintain the Jenkins configuration in a Git repo.

11. About this website

12. Links and Literature

12.2. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT
The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”. The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.