Yolinux.com Tutorial Jenkins logo

Jenkins:

Continuous Integration (CI) or periodic build and regression test

This tutorial covers the installation, configuration and use of the Jenkins build server on Linux. Jenkins is an automated software build and regression test server framework which integrates with your CM system to build and test your software continuously upon every check-in or scheduled for a periodic build and test (e.g. nightly).

The Jenkins Continuous Integration (CI) product forked in January 2011 from the Hudson CI project. Oracle maintains the Hudson product and the origional developers continued the project with the new open source project name: Jenkins.

This Jenkins tutorial depricates the prior Hudson tutorial.

Jenkins Tutorial Contents:

Related YoLinux tutorials:

°Cabie Build Server

°Web server configuration

°Subversion and Trac

°Java JUnit tests

°C++ CppUnit tests

°YoLinux Tutorials Index




Free Information Technology Magazines and Document Downloads
TradePub link image


Free Information Technology Software and Development Magazine Subscriptions and Document Downloads


Introduction to Jenkins:

Jenkins can monitor your CM system to detect a check-in. Upon recognition of this change, Jenkins will update a local working directory of code and perform a series of build steps (e.g. "ant clean", "ant compile" or "make clean" and "make"). Unit tests and tests can be performed after each build. Jenkins can support multiple CM systems (SVN, CVS, GIT, Clearcase, ...) and build frameworks. It can work as a stand-alone server or collectively in a master with multiple reporting nodes configuration to support builds on a variety of OS's and configurations. Jenkins supports Ant, Maven or a sequence of shell script based builds, code analysis and unit or integration tests. Jenkins has many plug-ins available to extend its feature set and to integrate with other Software tools.

This tutorial will cover the installation, configuration and use of Jenkins integrated with an existing Apache server used as a CM web portal.

Other related YoLinux.com Tutorials:

       

Jenkins logo


Installation and Configuration:

Download:

Two example installations:
  1. Basic WAR file and start script
  2. Linux RPM Package (Red Hat/Fedora/CentOS)

1) Basic Jenkins WAR File Configuration:

This example shows the basic Unix/Linux start script used to launch Jenkins. All configuration options in this example are set with environment variables and command line arguments:

#!/bin/bash

# Umask set so all in developer group can access and debug Jenkins jobs.
# Assign user jenkins to be in the developer group.
umask 002

export JENKINS_HOME=/var/jenkins
export JENKINS_USER="jenkins"
export JAVA_HOME=/usr/java/latest
export CLASSPATH=$JAVA_HOME/lib/tools.jar:./
export ANT_HOME=/opt/apache-ant-1.8.1
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$PATH
export JENKINS_PORT="8080"
export JENKINS_AJP_PORT="8009"
export JENKINS_DEBUG_LEVEL="5"
export JENKINS_ENABLE_ACCESS_LOG="yes"
export JENKINS_HANDLER_MAX="10"
export JENKINS_HANDLER_IDLE="20"

java -Djava.awt.headless=true -DJENKINS_HOME=$JENKINS_HOME -jar $JENKINS_HOME/jenkins.war --accessLoggerClassName=winstone.accesslog.SimpleAccessLogger --simpleAccessLogger.format=combined --simpleAccessLogger.file=$JENKINS_HOME/logs/access_log --prefix=/jenkins --daemon
Note --prefix=/jenkins is set for the Apache proxy configuration below
or access with the "/jenkins/" path appended to the URL http://localhost:8080/jenkins/

2) Red Hat Enterprise / CentOS RPM Configuration:

Jenkins is available as source, pre-built binaries and as an installable package.

Jenkins RPM Installation: rpm -ivh jenkins-1.487-1.1.noarch.rpm
/etc/init.d/jenkins
/etc/logrotate.d/jenkins
/etc/sysconfig/jenkins
/etc/yum.repos.d/jenkins.repo
/usr/lib/jenkins
/usr/lib/jenkins/jenkins.war
/usr/sbin/rcjenkins
/var/cache/jenkins
/var/lib/jenkins
/var/log/jenkins
Edit the init script: /etc/init.d/jenkins
Add the Java JRE path to line below (line 68):
for candidate in /usr/java/latest/bin/java /usr/lib/jvm/java-1.6.0/bin/java ...

See the YoLinux Java installation tutorial for more information.

Edit settings in /etc/sysconfig/jenkins
Define variables used by Jenkins init script.
JENKINS_HOME="/var/lib/Jenkins"
JENKINS_JAVA_CMD="/usr/java/latest/bin/java"
JENKINS_USER="jenkins"
JENKINS_ENABLE_ACCESS_LOG="yes"
JENKINS_PORT="8080"

...
JENKINS_HOME can be specified anywhere you like on the file system (eg: /opt/BUILDS/Jenkins)

An RPM installation will generate the user "jenkins".
A binary installation of Jenkins requires that you create the user:

useradd -d /var/lib/jenkins -c 'Jenkins user' jenkins.
chown -R jenkins.jenkins /var/lib/jenkins
Start Jenkins: /etc/init.d/jenkins start (or service jenkins start)

Note default service configuration: chkconfig --list |grep jenkins

jenkins         0:off   1:off   2:off   3:on    4:off   5:on    6:off
Jenkins can now be access by a web browser: http://jenkins.megacorp.com:8080/


Using Apache proxy to access Jenkins:

If you don't want users to access the Jenkins server directly but would rather that they access via an Apache web server at port 80 and use Apache authentication (e.g. LDAP, NIS, etc), route web traffic through the Apache server and use it as a proxy to access the Jenkins server.

  • Note that the Jenkins port is specified in the configuration file /etc/sysconfig/jenkins
    JENKINS_PORT="8080"
    ...
    
    Defines default Jenkins port.

  • Change the prefix Jenkins uses so that the default http://servername:8080/ can be accessed as http://servername:8080/jenkins

    This is achieved by adding the command line argument --prefix=/jenkins to the init script PARMS variable and restart Jenkins.

    Edit Jenkins init script: /etc/init.d/jenkins
    From:
    PARAMS="--logfile=/var/log/jenkins/jenkins.log --daemon"
    ...
    
    To:
    PARAMS="--logfile=/var/log/jenkins/jenkins.log --daemon --prefix=/jenkins"
    ...
    

    Restart Jenkins: /etc/init.d/jenkins restart

  • Configure Apache as a proxy to the Jenkins server service:

    Allow mod_proxy
    • Ubuntu:
      sudo apt-get install libapache2-mod-proxy-html
      a2enmod proxy
      a2enmod proxy_http
      
    • Red Hat: file /etc/httpd/conf/httpd.conf
      The default below remains as is:
      ...
      LoadModule proxy_module modules/mod_proxy.so
      LoadModule proxy_http_module modules/mod_proxy_http.so
      

      Create file:/etc/httpd/conf.d/jenkins.conf
      <IfModule mod_proxy.c>
       ProxyRequests     Off
      
       <Proxy http://localhost:8080/jenkins*>
         Order deny,allow
         Allow from all
       </Proxy>
      
       ProxyPass         /jenkins  http://localhost:8080/jenkins
       ProxyPassReverse  /jenkins  http://localhost:8080/jenkins
      
      # <Location /jenkins/>
      #   AuthType basic
      #   AuthName "Jenkins"
      #   AuthUserFile "/srv/passwd/.htpasswd"
      # </Location>
      
      </IfModule>
      

    Restart web server: service httpd restart
    or: apachectl restart

  • Block external access to the Jenkins server on port 8080 (only localhost allowed) and only allow network proxy access through Apache on port 80 with the following firewall rules:

    Add to end of /etc/rc.local so it executes upon system boot.

    # Allow loopback access. 
    # Rule for your computer to be able to access itself via the loopback
    # This rule must come before the rules denying port # access!!
    iptables -A INPUT -i lo -p all -j ACCEPT
    iptables -A OUTPUT -o lo -p all -j ACCEPT
    iptables -A INPUT -p tcp -s 0/0 -d 0/0 --dport 8080 -j DROP
    

    SELinux: setsebool -P httpd_can_network_connect true

  • Jenkins can now be accessed with a web browser: http://jenkins.yourdomain.com/jenkins/


Ant Build script: (example)

Jenkins can execute scripts, use Apache Ant or Maven build tools. In this example I am using Ant to launch a make file. Typical Java programmers will not need this example and will typically have projects which build with Ant or Maven. Projects based on Makefile builds (typical for C, C++, FORTRAN, etc) may want to use Apache Ant to call makefile targets as shown in this example.

Installation: (choose one option)
  • Install binary tar ball:
    cd /opt
    wget http://mirrors.kahuki.com/apache/ant/binaries/apache-ant-1.8.0RC1-bin.tar.gz
    tar xzf apache-ant-1.8.0RC1-bin.tar.gz
  • Use Red Hat Enterprise 5 YUM (Apache Ant 1.6): yum install ant
Create Ant build script to launch make file targets:
File: build.xml
<project name="projectX" default="jenkins" basedir=".">
    <description>
        Jenkins Ant file for projectX
    </description>
  <!-- set global properties for this build -->
  <property name="app" location="projectx"/>
  <property name="make.cmd" value="/usr/bin/make"/>
  <property name="build.native" value="./"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
  </target>

  <target name="compile"
        description="compile the source" >
    <exec dir="${build.native}" executable="${make.cmd}" failonerror="true">
    </exec>
  </target>

  <target name="clean"
        description="clean up" >
    <exec dir="${build.native}" executable="${make.cmd}" failonerror="true">
    <arg value="clean"/>
    </exec>
  </target>

</project>

Links:


MS/Visual C++:

DOS commands to clean and build:
  • devenv.exe projectX.sln /clean debug
  • devenv.exe projectX.sln /build debug

Example CMD DOS command scripts to clean and build:

Environment variables for use with the MS/Visual Studio compiler can be found in:

  • MS/Visual Studio .NET 2003: C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat
  • MS/Visual Studio 8.0: C:\Program Files\Microsoft Visual Studio 8\VC\vcvarsall.bat
Also see the YoLinux DOS / bash command comparison


Wind River Workbench / VxWorks:

Example of a build for embedded RTOS development using Wind River Workbench / VxWorks:

File: build.xml
<project name="Embedded VxWorks Build for ProjectE" default="jenkins" basedir=".">
    <description>
        Jenkins Ant file for Embedded VxWorks Build for ProjectE
    </description>
  <!-- set global properties for this build -->
  <property name="make.cmd" value="/opt/WindRiver/utilities-1.0/x86-linux2/bin/make"/>
  <property name="genmake.cmd" value="/opt/WindRiver/workbench-3.1/x86-linux2/bin/wrws_update.sh"/>
  <property name="build.native" value="./"/>
  <property environment="env"/>

  <target name="init">
    <!-- Create the time stamp -->
    <tstamp/>
  </target>

  <target name="genmake" description="Generate Makefile from .project file" >
    <exec dir="${build.native}" executable="${genmake.cmd}" failonerror="true">
    <arg line="-data /home/builds/jobs/ProjectE/workspace -l ProjectE -m"/>
    <env key="WIND_HOME" value="/opt/WindRiver"/>
    <env key="WIND_BASE" value="/opt/WindRiver/vxworks-6.7"/>
    <env key="PATH" value="/opt/WindRiver/diab/5.7.0.0/LINUX386/bin:${env.PATH}"/>
    <env key="LD_LIBRARY_PATH" value="/opt/WindRiver/vxworks-6.7/host/x86-linux2/lib:${env.LD_LIBRARY_PATH}"/>
    <env key="WIND_PLATFORM" value="vxworks-6.7"/>
    <env key="LM_LICENSE_FILE" value="/opt/WindRiver/license/zwrsLicense.lic"/>
    </exec>
  </target>

  <target name="compile" depends="genmake" description="compile the source" >
    <exec dir="${build.native}" executable="${make.cmd}" failonerror="true">
    <arg line="-f PPC604diab/Makefile clean main_all"/>
    <env key="WIND_HOME" value="/opt/WindRiver"/>
    <env key="WIND_BASE" value="/opt/WindRiver/vxworks-6.7"/>
    <env key="PATH" value="/opt/WindRiver/diab/5.7.0.0/LINUX386/bin:${env.PATH}"/>
    <env key="LD_LIBRARY_PATH" value="/opt/WindRiver/vxworks-6.7/host/x86-linux2/lib:${env.LD_LIBRARY_PATH}"/>
    <env key="WIND_PLATFORM" value="vxworks-6.7"/>
    <env key="LM_LICENSE_FILE" value="/opt/WindRiver/license/zwrsLicense.lic"/>
    </exec>
  </target>

</project>
Note that much of this configuration is devoted to setting the environment variables PATH, LD_LIBRARY_PATH and VxWorks environment variables. The VxWork paths should preceed all others so that VxWorks provided tools such as tclsh, used for auto code generation, will be used instead of the Linux tools as they may operate differently due to version and release variations.
This ANT build script first generates the Makefile from the Workbench GUI IDE project file. It then compiles the code using the Makefile.

This configuration is of Apache, Jenkins and the Wind River workbench compiler all running on Linux. (Note that the Windriver Workbench/VxWorks installation CDs contain both the Microsoft Windows and Linux installations on the same CD)


Jenkins Build Configuration:

From the Jenkins web page: http://jenkins.megacorp.com/jenkins/

  • Select "Manage Jenkins" (upper left)
    (URL: http://jenkins.megacorp.com/jenkins/manage)
    Jenkins manage screen shot

  • Select "Configure System":
    • Set Ant configuration:
      Set default ANT and JDK Jenkins configuration
      (URL: http://jenkins.megacorp.com/jenkins/configure)
      Specify ANT_HOME path. When configuring a Jenkins project, you must not take the Ant (default) but must specify this version of Ant. Common Pitfall!
      Can get error:
      FATAL: command execution failed.Maybe you need to configure the job to choose one of your Ant installations?
      java.io.IOException: Cannot run program "ant"
    • Set "Global Properties" + "Environment variables" - List of key-value pair
      Environment VariableValue
      ANT_HOME/opt/apache-ant-1.8.0RC1
      PATH$ANT_HOME/bin:$PATH
      CLASSPATH/usr/java/latest/lib/tools.jar:./
    • Subversion: Set URL to repository.

  • Select "create new jobs"
    • Enter a job name and type ("Build a free-style software project" + OK
    • Source Code Management:
      Select CM (i.e. Subversion). If Subversion then also enter the repository URL: http//svn.megacorp.com/svn/ProjectX/trunk
      You will be prompted for authentication login/password if required.
      Check "Use update"
    • Build Triggers:
      Select "Poll SCM" and define a schedule:
      Poll CM system (e.g. Subversion) every 6 minutes (10 times an hour) for updates.
      */6  * * * *
            
      This will detect changes checked into the CM system to trigger a new build.

      Chose a time which is greater than the time to update the local working Subversion repository, compile and run any regresion tests. Configure to handle even the longest of JUnit or CppUnit tests.

      Run build at 2:00am every Tuesday-Saturday
      0 2 * * 2-6
            
      This will run like a nightly build cron job.
    • Build:
      Select from the pulldown list "Invoke Ant" and enter list of targets eg: clean and all
    • Unit Tests:
    • Select "E-mail Notification" and enter email address.
      (Make sure you are running an SMTP daemon: service sendmail start)
    • Select "Save"
Test the system by selecting "Build Now" (upper left hand side of page.)


Jenkins Artifacts:

Define list of build artifacts:
  • From the Jenkins home page select the Job.
  • From the upper left hand side of the page, select the "Configure" link.
  • In the section "Post-build Actions" select the option "Archive the artifacts".
  • Files to archive: name-your-executable-or-lib-here
    (Comma separated list. Can use **/file.ext notation)
  • After the next build, the project page will show the package icon and list the "Last Successful Artifacts" you specified.
    Jenkins package icon


Jenkins Plug-ins:

Jenkins plug-ins are a way of extending and enhancing the capability of Jenkins. Many plug-ins provide an interface with other systems to provide improved integration. One of the wonderful features of Jenkins is the seamless integration of the plug-in installation: Jenkins (start page) + "Manage Jenkins" + "Manage Plugins". Now select the "Available" tab. From here you can select the plugin for Jenkins to download and install.

See the current list of Jenkins plug-ins

Jenkins can download and manage plugins from the web console but the "hpi" plugin files can also be downloaded (Jenkins hpi plugins) indepedently and placed in the plugins directory: /var/lib/jenkins/plugins/ Note that this directory gets generated by Jenkins after first use when it starts up.

I do recommend some as part of any Jenkins installation, the Source Lines Of Code (SLOC) plugin "SLOCCount", "Sidebar-Link", Disk Usage and "Green Balls" plugins.

Plugins:
  • Sidebar: Allow one to post links in the "side" bar.
  • SLOCCount: Post results from a run of the program "sloccount".
  • dOxygen: Link to dOxygen generated documentation from Jenkins.
[Potential Pitfal]: Jenkins version 1.4xx requires Java 1.5 or newer. If running on a Solaris 8 platform you will be limited to Java 1.5 as your latest version. Note that some plugins are compiled with later versions of Java and may cause unexpected errors.
FATAL: java.lang.String.isEmpty()Z
   java.lang.NoSuchMethodError: java.lang.String.isEmpty()Z
   at jenkins.plugins.doxygen.DoxygenDirecotryParser.getDoxygenGeneratedDir(DoxygenDirectoryParser.java:126)
In this error, the Doxygen plugin makes a call to isEmpty() which is a method available with Java 1.6 but not 1.5.
An alternative solution is to use the "sidebar link" to point to the location of the generated documents:
    /job/project-name/ws/doc-path/html/index.html


Sidebar-Link Plugin:

Allows one to generate a list of extra links for Jenkins main page and view tabs. I use this to generate a link back to our CM server home page.

  • Install Sidebar-Link plugin:
    • Jenkins (start page) + "Manage Jenkins" + "Manage Plugins".
    • Select the "Available" tab.
    • Select plugin "Sidebar" (under the "User Interface" category) for installation.
    • Then select the "Install" button at the bottom of the page.

  • Configure Plug-in:
    • After installing plug-in, go to your Jenkins home page and select "Manage Jenkins" + "Configure System".
    • There will now be a new option category "Additional Sidebar Links".
    • Select the button "Add Link" and specify the following:
      • Link URL:
      • Link Text:
      • Link Icon:
        Note: that an "Icon" specified as /userContent/ProjectX_logo_24x24.gif would reside in the local file system as $JENKINS_HOME/userContent/ProjectX_logo_24x24.gif (according to documentation) but found $JENKINS_HOME/war/images/24x24/ProjectX_logo_24x24.gif works where $JENKINS_HOME is defined in Jenkins configuration file /etc/sysconfig/jenkins
        Also set: chown jenkins.jenkins /var/lib/jenkins/war/images/24x24/ProjectX_logo_24x24.gif
        Note that icons in this directory can be identified by the file name without referencing the full path (Jenkins is aware of this icons directory).
    • Select button "Save".

Jenkins Sidebar-Link Plugin


SLOCCount Plugin:

This plugin will run the sloccount program against your code and report results through Jenkins.

  • Install "sloccount":
    • wget http://www.dwheeler.com/sloccount/sloccount-2.26.tar.gz
    • tar xzf sloccount-2.26.tar.gz
    • cd sloccount-2.26
    • links sloccount.html
      ("q" to quit) Install info is at the bottom of the page.
    • vim makefile (or use your favorite editor)
      • PREFIX=/opt/sloccount
      • POSTED_DIR=/root/Admin/sloccount
    • make
    • mkdir -p /opt/sloccount/bin
    • make install

    SlocCount home page

    [Potential Pitfall]: Compilation error:
    # make
    gcc -Wall c_count.c -o c_count
    cp -p c_count java_count
    gcc -Wall lexcount1.c -o lexcount1
    flex -Cfe -t pascal_count.l > pascal_count.c
    /bin/sh: flex: command not found
    make: *** [pascal_count.c] Error 127
        
    Solution to missing dependency:
    • Ubuntu/Debian: yum install flex
      or
    • apt-get install flex

  • Install SLOCCount plugin:
    • Jenkins (start page) + "Manage Jenkins" + "Manage Plugins".
    • Select the "Available" tab.
    • Select plugin "SLOCCount" (under the "Build Reports" category) for installation.
    • Then select the "Install" button at the bottom of the page.

  • Configure Jenkins System:
    After installing plug-in ad restarting Jenkins, go to your Jenkins home page and select "Manage Jenkins" + "Configure System".
    (http://jenkins.megacorp.com/jenkins/configure)
    In the section "Global Properties" + "Environment Variables", add to your PATH:
    • name: PATH
    • value: $ANT_HOME/bin:/opt/sloccount/bin:$PATH
    Then select "Save" at bottom of page.

  • Jenkins Project Configuration:
    • Select your build job from the Jenkins home page.
    • Select "Configure" (top left hand side of page)
    • At the bottom of page under "Post-build Actions" select the "Publish SLOCCount analysis results " box.
    • Set SLOCCount reports: **/sloccount.sc
      (this is the default)
    • Select the "Save" button to save this configuration.

  • Configure Build:
    • Shell Script:
      export PATH=$PATH:/opt/sloccount
      sloccount --wide --details src/ProjectX > sloccount.sc
              
    • Ant: Add target "sloccount"
      (add to build.xml)
      File: build.xml
      ...
      ...
        <property name="basedir" value="./"/>
      
        <target name="sloccount"
                description="Source Lines Of Code count" >
          <delete file="${basedir}/sloccount.sc"/>
          <mkdir file="${basedir}/slocdata"/>
          <exec executable="/opt/sloccount/bin/sloccount" 
                dir="${basedir}"
                output="sloccount.sc"
                failonerror="true">
             <arg line="--duplicates --wide --details --addlangall --datadir slocdata ."/>
             <env key="PATH" value="/opt/sloccount/bin:${env.PATH}"/>
          </exec>
        </target>
      
      ...
      ...
      

After the build following this configuration, there will now be a new link on the upper left corner of the page labeled "SLOCCount". Select to show the SLOC report.

Jenkins SLOCCount Plugin


dOxygen Plugin:

This plugin will allow you to view doxygen documentation through Jenkins. Note that this plugin does not perform the document generation but just allows one to view the results as a link from within Jenkins.

  • Install dOxygen plugin:
    • Jenkins (start page) + "Manage Jenkins" + "Manage Plugins".
    • Select the "Available" tab.
    • Select plugin "Doxygen" (under the "Build Reports" category) for installation.
    • Then select the "Install" button at the bottom of the page.

  • Jenkins Project Configuration:
    • Select your build job from the Jenkins home page dashboard.
    • Select "Configure" (top left hand side of page)
    • At the bottom of page under "Post-build Actions" select the "Publish Doxygen" box.
    • Set Doxygen config file:
      Doxygen path: ProjectX/Doxyfile.cfg
      Note that this is the configuration file used by dOxygen to generate the report.
    • Select the "Save" button to save this configuration.

  • Configure Build:
    Add dOxygen document generation to your build by adding the ant target "doxygen".
    File: build.xml
    ...
    ...
      <property name="build.native" value="./"/>
      <property name="doxygen.cmd" value="/usr/bin/doxygen"/>
    
      <target name="clean" description="clean up" >
        <delete quiet="true">
          <fileset dir="Docs/html" includes="**/*" />
        </delete>
      </target>
    
      <target name="doxygen"
              description="Process documentation" >
        <exec executable="${doxygen.cmd}" 
              dir="${build.native}"
              failonerror="false">
           <arg value="Doxygen.cfg"/>
        </exec>
      </target>
    
    ...
    ...
    

  • Configure dOxygen:
    DOxygen is typically installed on Linux systems during the initial install, with yum, by RPM or apt-get. This is detailed in the YoLinux Systems Administration tutorial.

    The generation of the dOxygen configuration file and settings are detailed in the YoLinux dOxygen and C++ tutorial.

    The Jenkins dOxygen plugin uses the dOxygen config file to locate the generated dOxygen documentation.

    [Potential Pitfall]: The dOxygen configuration file uses the directive "OUTPUT_DIRECTORY" to locate the output for the generated documentation. This may not have the correct directory prefix to match the Subversion base directory as viewed from Jenkins. Thus it may be necessary to create a new dOxygen configuration file to fool Jenkins into looking in the proper directory.

    Example: original dOxygen configuration file may reference the path as follows:
    File: Doxygen.cfg
    ...
    ...
    OUTPUT_DIRECTORY       = Docs
    ...
    ...
            
    In order for Jenkins the find the documentation files, generate a new dOxygen configuration will with the correct relative path:
    File: JenkinsDoxyfile.cfg
    # File to trick Jenkins dOxygen plugin to find HTML reports location
    PROJECT_NAME           = ProjectX
    OUTPUT_DIRECTORY       = ProjectX/Docs
    OUTPUT_LANGUAGE        = English
    GENERATE_HTML          = YES
    HTML_OUTPUT            = html
    
    This file only used to trick Jenkins into looking at the correct location and is not a proper dOxygen configuration file for generating documentation.
    Jenkins will now look in ProjectX/Docs/html/ for the files.

Jenkins Doxygen Plugin


Jenkins Security:

Security can be handled by Apache authentication and authorization if proxied through Apache as detailed above or by Jenkins itself.

Turning on Jenkins security: Jenkins (home page/dashboard) +"Manage Jenkins" + Configure system"
Options:
  • Jenkins's own user database
  • LDAP
  • Delegate to servlet container
  • Unix user/group database (PAM)

Authorization can also be handled by Jenkins options from nothing to setting fine grained Global or Project based authorization control.

Definitions:
  • Authentication: user proves that they are indeed who they say they are. Login and password required.
  • Authorization: user is allowed (authorized) to perform certain functions and have specific access. eg. admin, read only, etc.


Notes:
  • Best Practices:
    • Proxy Jenkins through the Apache web server on port 80 so that all web based tools authenticate through the same Apache authentication system and port (80). Very amateur configurations send you to ports like 8080, 8181, 9090 for each web application. Proxy all of them through port 80.
    • Run the Jenkins-CI build server on the build platform (unless Java is not available like many embedded platforms). This will be self evident for unit test report generation which does not return through stdout/stdin. Jenkins is written in Java and will run on most platforms.
    • Sidebar link plugin is very useful for making reports and results files available for viewing.
    • Use Ant with build targets and not raw shell commands except in the simplest of configurations. It is easier to add/remove Ant targets at will. Ant is a build tool and comes with many useful options. Yes, it can be used to call make.
    • Versions of plugins MUST match the Jenkins war file. Violate this and you will eventually get crashes -

  • The config file /etc/sysconfig/jenkins defines the "JENKINS_HOME" directory under which all of the build jobs and configurations are stored.

  • View Build Results: From the Jenkins web page http://jenkins.megacorp.com/jenkins/, select the job and from the build history then select a build.
    Feedback from the build is available from the left hand side link "Console Output".

  • Jenkins will perform a code checkout to $JENKINS_HOME/jobs/Jenkins/workplace/projectx
    Where JENKINS_HOME is defined in /etc/sysconfig/jenkins

  • Jenkins build numbers do not necessarily match Subversion version numbers. It may not be possible to synchronize Jenkins build numbers if more than one build is generated from the source repository. For example, if Subversion has source control for four executables, then for each check-in and revision increment of Subversion, there may be no build, one build or more triggered in Jenkins.

  • Look for errors in /var/log/jenkins.log

  • Example shell execution:
    Jenkins shell command execution

  • Jenkins architecture: Jenkins is a servlet written in Java and runs in the Winstone servlet engine.

  • Jenkins updates: Jenkins will notify you of Jenkins software updates and allow you to download a new Jenkins WAR file. You will get an update message similar to the one below:
    Jenkins update message

  • Jenkins file and directory permissions: Updates and other functions may end in Java errors if directory ownership or permissions are not correct. I got an error message during an upgrade which stated that the file /usr/lib/jenkins/jenkins.war.tmp could not be created. The fix is to make sure that the directory has the proper security settings. I run Jenkins under user "jenkins". My fix:
    chown jenkins.jenkins /usr/lib/jenkins/

  • Proxy server configuration:
    Choose one option:
    • Add proxy configuration to bash shell environment:
      Edit user "jenkins" bash shell configuration file: /var/lib/jenkins/.bashrc
      export http_proxy=http://proxy.megacorp.com:80
      ...
              
      Used by Jenkins and plugin updates.
    • Add proxy configuration to Jenkins configuration:
      • Select "Jenkins" (Jenkins home) + "Manage Jenkins" + "Manage Plugins".
      • Select the "Advanced" tab:
        Server: http://proxy.megacorp.com
        Port: 80
      If your proxy does not use a login/password, ignore the default password that gets placed in the text entry box. It is ignored and it can't be set to a blank field.
      Jenkins proxy server configuration
    • Edit proxy configuration file:
      • Look for definition of JENKINS_HOME in file /etc/sysconfig/jenkins
      • Edit proxy setting is proxy config file: JENKINS_HOME/proxy.xml

  • [Potential Pitfall]: Running Jenkins on the same system with another servlet engine such as Tomcat or JBoss. You may find that you get errors and experience TCP/IP port conflicts if you run Jenkins on the same platform as another servlet engine. You will most probably experience conflicts on the HTTP or AJP ports. The setting of the HTTP port is detailed above. To turn off the AJP port, set it to "-1" by adding the following command line argument: --ajp13Port=-1 (-1: disable). To specify an AJP port just set it to the port value desired instead of "-1".

    This command line argument can be set in /etc/sysconfig/jenkins
    Change from:
    ...
    JENKINS_ARGS=""
            
    To:
    ...
    JENKINS_ARGS="--ajp13Port=-1"
            
    A full list of arguments can be found by issuing te following command:
    java -jar /usr/lib/jenkins/jenkins.war --help
    Restart Jenkins: /etc/init.d/jenkins restart
    Verify the command: ps -auxw | grep jenkins

    Note that the AJP port is used to connect the Apache web server with the servlet engine. If using AJP and you change the default AJP port, remember to set /etc/httpd/conf.d/proxy_ajp.conf to the new port number.

  • [Potential Pitfall]: Port conflict on port 34377?

    Jenkins can work as a cluster of build servers specialized for various platforms. They will communicate using JNL TCP/IP port 34377 (default setting)

    If you are not using this master - slave custer arrangement, turn it off:
    • Select the link "Jenkins" + "Configure System"
    • Select the box "Enable security" category "TCP post for JNLP slave agents"
    • Select the radio button "Disable"
    • Select "Save" at the bottom of the page

  • Contiuous Integration requires a build/compile but is best if some sort of test is applied to verify the correctness of the code. Many unit test frameworks are available to support unit tests. See the YoLinux.com list of testing frameworks for C/C++ and Java

  • Project configuration option: “Send separate e-mails to individuals who broke the build”. Jenkins assumes that the user email addresses are the CM (eg Subversion) "user-id" + a specified suffix (eg @megacorp.com). If this is not the case try using the Jenkins LDAP plugin where Jenkins will pull the correct email address from LDAP. Another option is to set up Postfix to forward Jenkins generated localhost emails to their corporate accounts. The Postfix virtual users can have forwarding email addresses to their corporate email addresses.


Books icon Books:

publisher cover Continuous Integration: Improving Software Quality and Reducing Risk
(Paperback)
by Steve Matyas, Andrew Glover
Addison-Wesley Professional

Amazon.com
publisher cover Jenkins: The Definitive Guide
(Paperback)
by John Ferguson Smart
O'Reilly Media (July 27, 2011)

Java development focus.

Amazon.com
publisher cover Better Software Magazine

Free subscription for software professionals who care about quality. Each issue brings you relevant, timely information to help you build better software. Continuing to deliver in-depth articles on testing, tools, defect tracking, metrics, and management.

Free
Subscription
   

    Bookmark and Share


Advertisements




Copyright © 2012 - 2013 by Greg Ippolito