Jenkins

From KevinWiki

Jenkins is a continuous integration tool built using Java. It can work as a standalone server since it has the Winstone Servlet Container or it can work on various Servlet Containers or JEE servers such as Apache Tomcat, Glassfish, JBoss, IBM WebSphere, Jetty 6, etc. Jenkins supports Apache Ant and Maven as well as SCM tools such as CSV and Subversion.

Installation

• Download the latest Jenkins from the Jenkins web site.
• Deploy jenkins.war file as a web application to Tomcat server.

Use Subdomain to Access Jenkins (with SSL)

• Install and enable mod_jk.
• Open the workers.properties file in the /etc/apache2 directory.
• Add a new worker for Jenkins.

workers.tomcat_home=/opt/tomcat
workers.java_home=/usr/lib/jvm/java-6-sun
ps=/
worker.list=worker1,jenkins
worker.worker1.port=8009
worker.worker1.host=localhost
worker.worker1.type=ajp13
worker.worker1.lbfactor=1
worker.jenkins.port=8009
worker.jenkins.host=jenkins.yourdomain.com
worker.jenkins.type=ajp13
worker.jenkins.lbfactor=1

• Set up JkMount in the apache virtual host configuration.

<VirtualHost *:443>
    ServerAdmin master@yourdomain.com

        SSLEngine on

        SSLOptions +StrictRequire

        SSLCertificateFile /etc/ssl/certs/server.crt
        SSLCertificateKeyFile /etc/ssl/private/server.key

    ServerName jenkins.yourdomain.com

    JkMount / jenkins
    JkMount /* jenkins

</VirtualHost>

• Open the $CATALINA_HOME/conf/server.xml file to set up a new tomcat virtual host for the jenkins.
• Add the virtual host info inside the Engine element.

    <Engine name="Catalina" defaultHost="localhost">
      ... Default Host Info ...
 
      <Host name="jenkins.yourdomain.com" appBase="/opt/tomcat_user_dir/jenkins_webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false">
      </Host>
    </Engine>

• If the virtual host is for Jenkins only (e.g. http://jenkins.yourdomain.com),

1. Remove all the files and directories in the appBase directory which is, in the example above, /opt/tomcat_user_dir/jenkins_webapps.
2. Copy jenkins.war file to the appBase directory and change jenkins.war to ROOT.war.

• Restart tomcat and apache.

$ /etc/init.d/tomcat stop 
$ /etc/init.d/tomcat start 
$ /etc/init.d/apache restart 

• access https://jenkins.yourdomain.com.

Known Problem

More than One Jenkins Instance

• This problem will not happen if the instructions above are used to install Jenkins.

• If Jenkins complains about two jenkins instances using the same JENKINS_HOME with the following error message, stop the tomcat server and check $CATALINA_HOME/work directory and removes duplicate ones if found.

Jenkins detected that you appear to be running more than one instance of Jenkins that share the same home directory 
...
This greatly confuses Jenkins and you will likely experience strange behaviors, so please correct the situation.

• Check server.xml.
• If the virtual host is only for Jenkins and server.xml has the virtual host setup like below with jenkins.war placed in the webapps directory, Tomcat server will create two instances (jenkins and ROOT) of Jenkins when it starts.

    <Engine name="Catalina" defaultHost="localhost">
      ... Default Host Info ...
 
      <Host name="jenkins.yourdomain.com" appBase="/opt/tomcat_user_dir/jenkins_webapps"
            unpackWARs="true" autoDeploy="true"
            xmlValidation="false" xmlNamespaceAware="false">
          <!-- WARNING: This is WRONG!!! -->
          <Context path="" docBase="jenkins" debug="0" reloadable="true" />
      </Host>
    </Engine>

• To solve this problem, as mentioned already (Read the instructions to Use Subdomain to Access Jenkins (with SSL)),

1. Remove all the files and directories in the appBase directory which is, in the example above, /opt/tomcat_user_dir/jenkins_webapps.
2. Copy jenkins.war file to the appBase directory and change jenkins.war to ROOT.war.
3. Remove Context element in the server.xml file.

AWT is not properly configured

After installation and accessing jenkins, if it displays an error message like

AWT is not properly configured on this server. Perhaps you need to run your container with "-Djava.awt.headless=true"?

java.lang.InternalError: Can't connect to X11 window server using ':0.0' as the value of the DISPLAY variable.
(...)

Add the following line to the end of the $TOMCAT_HOME/conf/catalina.properties file (This is not necessary unless it has the error described above).

java.awt.headless=true

Configuration

• To set the Tomcat to use UTF-8 to decode URLs, open $CATALINA_HOME/conf/server.xml file.
• Add URIEncoding="UTF-8" to the following Connector element.

    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" />

• So it should be like this

    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" 
               URIEncoding="UTF-8" />

• If it uses mod_jk, add URIEncoding="UTF-8" to

    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

• So this should be

    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443"
               URIEncoding="UTF-8" />

• Restart the tomcat server.
• JkOptions +ForwardURICompatUnparsed option needs to be added to the /etc/apache2/mods-enabled/jk.load file or in the virtual host setup.

<VirtualHost *:443>
    ServerAdmin master@yourdomain.com

        SSLEngine on

        SSLOptions +StrictRequire

        SSLCertificateFile /etc/ssl/certs/server.crt
        SSLCertificateKeyFile /etc/ssl/private/server.key

    ServerName jenkins.yourdomain.com

    JkOptions +ForwardURICompatUnparsed

    JkMount / jenkins
    JkMount /* jenkins

</VirtualHost>

• Restart the apache server.