Table of contents
Install
Install JBoss Application server 4.2 or EAP 4.2
Download from here. Install in the usual way. For the zip distribution simply unzip in a directory of your choice.
If you are installing JBoss Application Server you'll end up having a directory called jboss-4.2.X.GA where X is the minor version of the server you've downloaded. Current latest version is 4.2.1.
If you are installing JBoss EAP 4.2 then you'll probably have a directory called jboss-eap-4.2.
I will call $JBOSS_HOME "jboss-eap-4.2/jboss-as" or jboss-4.2.X.GA depending on the what you've installed.
Set JENKINS_HOME
Just export JENKINS_HOME=<some dir> (UNIX) or set JENKINS_HOME=<some dir> (Windows) before starting JBoss Server.
Deploy jenkins.war
Copy jenkins war to "$JBOSS_HOME/server/<your server>/deploy". <your server> will most probably be "default" but could be "production" if you have installed JBoss EAP and have more than 2G RAM.
Start JBoss Server
cd $JBOSS_HOME
bin/run.sh -b 0.0.0.0 -c <your server>
Important! If you need security, e.g will enable jenkins security and have network connections to untrusted networks make sure to secure your jmx and web console before starting the server that way! JBoss EAP is secured by default but you should follow "getting started" instructions for the community release. Until you do, start the server with "-b 127.0.0.1" to be locally accessible only.
Access Jenkins GUI
Open in a browser http://<machine name>:8080/jenkins
Additional Configuration
JBoss startup
I would recommend setting at least 2 options when starting jboss as a container for jenkins- "-Djava.awt.headless=true" and "-Xmx<some reasonable value>".
The first one is even required for jenkins if there is no X server available by an UNIX installation but will safe you from troubles anyways. More information about headless mode here.
Then setting maximum available memory for use by the server depends on jobs that will be executed as well jenkins plug-ins that get used. We've hit out of memory issues with the junit report plug-in as it needs much memory to prepare big reports. Keep in mind that you will need to have enough memory to handle communications with slaves. And when getting OOM be sure to understand where does it come from - master or slave. To be able to handle the large number junit tests per job we've had to boost memory on both - master and slaves.
To pass these options you can set the environment variable JAVA_OPTS:
Linux: export JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true -Xmx<some reasonable value>" Windows: set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true -Xmx<some reasonable value>
As well you can modify run.sh/bat to avoid having that environment variable set for the child processes (jobs are one of them) you run. I use the following ugly bash script to avoid modifying that:
#!/bin/bash if [[ `dirname "$0"` != "." ]]; then cd `dirname "$0"` || exit 2 exec $SHELL -- `basename "$0"` "$@" fi ( JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true $MAX_JAVA_MEM" cd $JBOSS_HOME/bin . run.sh -c default -b 0.0.0.0 -u $MCAST_ADDR -g Jenkins ) &> ~/jenkins.log < /dev/null &
Make sure to have JBOSS_HOME and MAX_JAVA_MEM set.
Securing Jenkins
Configure login when delegating auth to container
FOR MORE COMPLETE DOCUMENTATION SEE http://www.jboss.org/community/docs/DOC-12188
I'll describe one easy way to do. It's most suitable for local installations or when you have the JBoss server dedicated for Jenkins. You could, of course, implement whatever authentication mechanism you need. Refer to the JBoss manual pages for more information. User forums and mailing lists are the best place to get help.
First you'll need to deploy jenkins unarchived:
- cd $JBOSS_HOME/server/<your server>/deploy/
- mkdir jenkins.war
- unzip <path>/jenkins.war
- cd jenkins.war/WEB-INF
- create file jboss-web.xml containing:
<jboss-web> <security-domain>java:/jaas/jmx-console</security-domain> </jboss-web>
Configure JBoss AS to do auth and secure
- Most steps are already done when using the JBoss Enterprise Application Platform
- cd $JBOSS_HOME/server/<your server>/conf/props
- add "jenkins=admin" to jmx-console-roles.properties
- add "jenkins=passwd" to jmx-console-users.properties
- restart server
Then: - enable security
- login as user "jenkins" with password "passwd"
Secure jmx and web console:
- edit $JBOSS_HOME/server/<your server>/conf/login-config.xml
- uncomment "<application-policy name = "jmx-console">" lines
- uncomment "<application-policy name = "web-console">" lines
- edit $JBOSS_HOME/server/<your server>/deploy/jmx-console.war/WEB-INF/jboss-web.xml
- uncomment <security-domain>
- edit $JBOSS_HOME/server/<your server>/deploy/jmx-console.war/WEB-INF/web.xml
- uncomment lines after "A security constraint that restricts access..."
- edit $JBOSS_HOME/server/<your server>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/jboss-web.xml
- uncomment <security-domain>
- edit $JBOSS_HOME/server/<your server>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml
- uncomment lines after "A security constraint that restricts access..."
Secure jmx-invoker:
- edit $JBOSS_HOME/server/<your server>/deploy/jmx-invoker-service.xml
- uncomment after "Uncomment to require authenticated users"
Secure HTTP-invoker:
- edit $JBOSS_HOME/server/<your server>/deploy/http-invoker.sar/invoker.war/WEB-INF/web.xml
- find <web-resource-name>HttpInvokers</web-resource-name>
- add additional <url-pattern> elements
- <url-pattern>/JNDIFactory/*</url-pattern>
- <url-pattern>/EJBInvokerServlet/*</url-pattern>
- <url-pattern>/JMXInvokerServlet/*</url-pattern>
You did twice the same so now you might be able to setup a different security domain for your jenkins installation and not "jmx-console" what I suggest above (see creating jboss-web.xml). See links below for more.
Configure login redirect to SSL
First you need to configure a SSL connector. Please refer to http://www.jboss.org/community/docs/DOC-11989 which is a thorough resource if you cannot get it going with the commented out example configuration.
Then you need to have the following in jenkins's web.xml:
<security-constraint> <web-resource-collection> <web-resource-name>Jenkins</web-resource-name> <url-pattern>/loginEntry</url-pattern> <url-pattern>/login</url-pattern> <!--http-method>GET</http-method--> </web-resource-collection> <auth-constraint> <role-name>*</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
Jenkins (JBoss) HTTP listening port
Edit $JBOSS_HOME/server/<your server>/deploy/jboss-web.deployer/server.xml and change `<Connector port="8080"' to `<Connector port="<some port>"'.
Context root and Virtual host
If you want to have jenkins on "/" instead of "/jenkins" by modifying jboss-web.xml.
<context-root>/</context-root> <!-- deploy to context root - not recommended - see below --> <virtual-host>host.example.com</virtual-host> <!-- if you want a specific virtual host -->
You'd better leave it be deployed under "/jenkins", otherwise some locations get inaccessible. To have both - convenience and usability you can use a simple redirection. To do that create the following files under server deploy directory:
redirect-jenkins.war/redirect.jsp redirect-jenkins.war/WEB-INF/jboss-web.xml redirect-jenkins.war/WEB-INF/web.xml
redirect.jsp should contain:
<% response.sendRedirect("/jenkins"); %>
jboss-web.xml should contain:
<jboss-web> <context-root>/</context-root> <!-- <virtual-host>jenkins.example.com</virtual-host> --> </jboss-web>
web.xml could be something like:
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <display-name>Redirecting to Jenkins</display-name> <description> Redirecting to Jenkins. </description> <welcome-file-list> <welcome-file>redirect.jsp</welcome-file> </welcome-file-list> </web-app>