Home Tutorials Training Consulting Products Books Company Donate Contact us









Online training

Events

Quick links

This article describes how to use the Jenkins continuous integration build server.

1. Using the Jenkins build server

Continuous integration is a process in which all development work is integrated as early as possible. The resulting artifacts are automatically created and tested. This process allows to identify errors as early as possible.

Jenkins is a popular open source tool to perform continuous integration and build automation. The basic functionality of Jenkins is to execute a predefined list of steps, e.g. to compile Java source code and build a JAR from the resulting classes. The trigger for this execution can be time or event based. For example, every 20 minutes or after a new commit in a Git repository.

Possible steps executed by Jenkins are for example:

  • perform a software build using a build system like Apache Maven or Gradle

  • execute a shell script

  • archive a build result

  • running software tests

Jenkins monitors the execution of the steps and allows to stop the process, if one of the steps fails. Jenkins can also send out notification in case of a build success or failure.

Jenkins can be extended by additional plug-ins. For example, you can install plug-ins to support building and testing Android applications.

2. Installation and setup of Jenkins

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

2.1. Installing of the Jenkins server on Ubuntu

Jenkins provides Debian/Ubuntu packages which install Jenkins and register Jenkins as start service. See the Install Jenkins on Ubuntu description The Linux installation creates a /etc/init.d/jenkins script which starts Jenkins automatically at boot time.

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

2.1.1. Using the .war file to start Jenkins

Download the jenkins.war file from Jenkins Homepage. From this file you can 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

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.

sudo mkdir .jenkins
sudo
chown tomcat7:nogroup .jenkins

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

3. Configure Jenkins

3.1. Connect to Jenkins for the initial configuration

After installation, open a browser and connect to it. The default port of Jenkins is :8080, therefore on your local machine you find it under the following URL:

http://localhost:8080/

You will need to copy the initial password from the file system of the server.

Afterwards you can select to install plug-ins. Select the Inst#ce9178all suggested plug-ins to get a typical configuration.

Create an admin user and press Save and Finish.

3.2. User management Jenkins

Select 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

3.3. Create a new 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

3.4. Generate ssh key for Jenkins user

If you want to access a private Git repo, for example at Github, you need to generate an ssh key-pair. Create a SSH key with the following command.

sudo -u jenkins ssh-keygen

The public key must be uploaded to the service you are using, e.g., Github.

3.5. Configure the default port of the Jenkins build server

sudo vim /etc/default/jenkins

++++
<!-- Non responsive Lake Quincy Ads
<div data-type="ad" data-publisher="lqm.javaeclipseandroid.site" data-zone="inBetween01" data-format="728x90">
</div> -->

<!-- Responsive Lake Quincy Ads -->
<div id='ad-inBetween01'>
    <script type='text/javascript'>
        googletag.cmd.push(function() { googletag.display('ad-inBetween01'); });
    </script>
</div>
++++

== Setting up a Jenkins job

The build of a project is handled via _jobs_ in Jenkins.
Select menu:New Item[].
Afterwards, enter a name for the job and select _Freestyle Job_ and press btn:[OK].

image::jenkins_createjob10.png[Setting up a Jenkins job]

Enter a description for the job and configure how many old jobs should be retained.

image::jenkins_createjob20.png[Setting up a Jenkins job]

Configure how the source code can be retrieved.
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.

image::jenkins_createjob30.png[Setting up a Jenkins job]

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

image::jenkins_createjob40.png[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.

image::jenkins_createjob50.png[Setting up a Jenkins job]

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

image::jenkins_createjob60.png[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.
Here you can analyze the build errors.



== Build Pipelines

Jenkins pipelines help you align the build process of a project.
This is done by specifying tasks and the order in which they are executed.
There are all kinds of possible tasks that a jenkins pipeline can do for you.
For example, build assets, send an email on error or send the build artifacts via SSH to your application server.

=== Setup using a Jenkinsfile

Jenkins allows to specify pipelines using a `Jenkinsfile`.
This is just a textfile that contains the necessary data for jenkins to execute the pipeline.
It is called `Jenkinsfile` (notice: no file extension) and should be placed in the root of your project.

NOTE: This file should be checked into version control as it is needed on your Jenkins instance.

Jenkins supports two different syntaxes.

1. Declarative (since Pipeline version 2.5)
2. Scripted

For this tutorial we will focus on the declarative approach.

The following example shows a pipeline with 2 stages:

[source,groovy]

pipeline { agent any <1>

	stages {
		stage('Build Assets') {
			agent any (1)
			steps {
				echo 'Building Assets'
			}
		}
		stage('Test') {
			agent any
			steps {
				echo 'Testing stuff...'
			}
		}
	}
}
<1> The `agent` directive tells jenkins to allocate a workspace and an executor for the pipeline.
Without it, the pipeline is not valid and therefore required.

=== Setup using the Blue Ocean plugin

The above process can also be done using the https://jenkins.io/projects/blueocean/[Blue Ocean] _Jenkins_ plugin.

==== Installation

To install the plugin go to menu:Manage Jenkins[Manage Plugins>Available] and select the _Blue Ocean_ plugin.

After the installation is finished you have an additional menu entry called btn:[Open Blue Ocean] in your main _Jenkins_ navigation.

image::jenkins_pipeline10.png[]

==== Creating a new pipeline

Click on btn:[New Pipeline] to create a new pipeline.

image::jenkins_pipeline20.png[]

Select your version control provider.

image::jenkins_pipeline21.png[]

NOTE: For this example we will use a github repository

Depending on your provider you will need to pass some kind of credentials.

NOTE: Github provides the ability to generate access-tokens that applications can use to access the platform with your user.
You can also restrict what the acess-token can do.

The _Blue Ocean_ application will provide a link to the GitHub page you need visit.
The necessary permissions that _Blue Ocean_ needs to operate are already selected.
Add a description and click on btn:[Generate Token] at the bottom of the page.

Copy the generated token and paste it in the _Blue Ocean_ mask.

Select the account the repository belongs to and select the repository.

image:jenkins_pipeline30.png[]

If you already have a `Jenkinsfile` with pipelines in the repository it will show up in the last step.
If not _Blue Ocean_ offers to create one for you.

==== Adding steps to your pipeline

In the next screen you will see a visual representation of your pipeline.
Here you can add or remove steps.

image:jenkins_pipeline40.png[]

To create a new stage click on btn:[+] in the canvas.
A menu will open on the right that lets you specify a name and what steps you want to perform.

image:jenkins_pipeline50.png[]

After you have finished editing the pipeline _Blue Ocean_ offers to commit the newly created pipeline to your repository.

Under the hood _Blue Ocean_ only created a valid `Jenkinsfile` for jenkins to use.

After committing _Jenkins_ will build the project using the newly modified pipelines.



[[hudsonlinks]]
== Jenkins links

https://jenkins-ci.org[Homepage of the Jenkins project]

http://blog.dahanne.net/2011/07/18/run-ui-tests-on-a-headless-jenkins-hudson-continuous-integration-server-running-ubuntu[Running tests on a headless Jenkins server]

https://www.howtoforge.com/tutorial/how-to-install-jenkins-with-apache-on-ubuntu-16-04/[Install Jenkins with Apache Http proxy]

== vogella training and consulting support

++++
<div class="about_vogella_container">
    <div class="about_vogella">
        <a href="https://learn.vogella.com/">
            <img src="https://www.vogella.com/img/common/logo_very_rough_white.svg"
            alt="Online Training" title="Online Training"
            onclick="_gaq.push(['_trackEvent', 'Buttom tutorial', 'clicked', 'Online Training']);"/>
            <h1>Online Training</h1>
        </a>
    </div>
    <div class="about_vogella">
        <a href="https://www.vogella.com/training/">
            <i class="material-icons md-48 white" onclick="_gaq.push(['_trackEvent', 'Buttom tutorial', 'clicked', 'Onsite Training']);">
                fitness_center
            </i>
            <h1>Onsite Training</h1>
        </a>
    </div>
    <div class="about_vogella">
        <a href="https://www.vogella.com/consulting/">
            <i class="material-icons md-48 white" onclick="_gaq.push(['_trackEvent', 'Buttom tutorial', 'clicked', 'Consulting']);">
                group
            </i>
            <h1>Consulting</h1>
        </a>
    </div>
</div>
++++


[appendix]
== Copyright, License and Source code

Copyright (C) 2012-2018 vogella GmbH.
Free use of the software examples is granted under the terms of the https://www.eclipse.org/legal/epl-2.0[Eclipse Public License 2.0].
This tutorial is published under the  http://creativecommons.org/licenses/by-nc-sa/3.0/de/deed.en[Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany] license.

https://www.vogella.com/license.html[Licence]

https://www.vogella.com/code/index.html[Source code]

https://www.vogella.com/support.html[Support free tutorials]

++++
<img src="https://ssl-vg03.met.vgwort.de/na/1ab85749424645bea98cfd96fdb946fc" width="1" height="1" alt="" />
++++