Jenkins - Tomcat Setup

Jenkins – Tomcat Setup (Optional)

While running Jenkins via java -jar jenkins.war or using Docker is common, you can also deploy Jenkins as a web application (.war file) inside a servlet container like Apache Tomcat. This might be preferred if you already manage other applications in Tomcat.

Note: This method adds the complexity of managing Tomcat alongside Jenkins. For simpler setups, consider the standalone or Docker options first.

Prerequisites

1. Java Development Kit (JDK): Jenkins requires a compatible JDK (Java 11 or 17 recommended) to run. Tomcat also requires Java. Ensure the JDK is installed and the JAVA_HOME environment variable is set correctly.
2. Apache Tomcat: Download and install a recent version of Tomcat (e.g., Tomcat 9.x or 10.x) from the official website: https://tomcat.apache.org/
3. Jenkins WAR File: Download the ‘Generic Java package (.war)’ file from https://www.jenkins.io/download/

Step 1: Verify Java Installation

Open your terminal or command prompt and run:

java -version

Ensure the output shows a compatible version (e.g., 11.x.x or 17.x.x).

# Example Output (Linux/macOS)
openjdk version "11.0.15" 2022-04-19
OpenJDK Runtime Environment (build 11.0.15+10-Ubuntu-0ubuntu0.20.04.1)
OpenJDK 64-Bit Server VM (build 11.0.15+10-Ubuntu-0ubuntu0.20.04.1, mixed mode, sharing)

# Example Output (Windows)
java version "17.0.3" 2022-04-19 LTS
Java(TM) SE Runtime Environment (build 17.0.3+8-LTS-111)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.3+8-LTS-111, mixed mode, sharing)

Also verify JAVA_HOME is set:

# Linux/macOS
echo $JAVA_HOME

# Windows
echo %JAVA_HOME%

Step 2: Prepare Tomcat

1. Download the appropriate Tomcat binary distribution (e.g., zip or tar.gz) for your OS.

2. Extract the downloaded archive to a suitable location (e.g., /opt/tomcat or C:\Program Files\Tomcat). This location is referred to as CATALINA_HOME.

3. Memory Configuration (Recommended): Jenkins often requires more memory than Tomcat’s default. Edit the Tomcat startup script environment settings. Create or modify CATALINA_HOME/bin/setenv.sh (Linux/macOS) or CATALINA_HOME/bin/setenv.bat (Windows) and add Java options:

# Example setenv.sh (Linux/macOS)
export CATALINA_OPTS="$CATALINA_OPTS -Xms1G -Xmx2G -Djenkins.install.runSetupWizard=false"

# Example setenv.bat (Windows)
set CATALINA_OPTS=%CATALINA_OPTS% -Xms1G -Xmx2G -Djenkins.install.runSetupWizard=false

Adjust -Xms (initial heap size) and -Xmx (maximum heap size) based on your server’s resources (e.g., 1GB initial, 2GB max). The -Djenkins.install.runSetupWizard=false flag can optionally disable the initial setup wizard if you pre-configure Jenkins.

Step 3: Deploy Jenkins WAR

1. Locate the jenkins.war file you downloaded.

2. Copy the jenkins.war file into the CATALINA_HOME/webapps/ directory.

Step 4: Start Tomcat

1. Open your terminal or command prompt.

2. Navigate to the CATALINA_HOME/bin directory.

3. Run the startup script:

# Linux/macOS
./startup.sh

# Windows
startup.bat

Tomcat will start, and you should see messages indicating it’s deploying the jenkins.war file in the logs (e.g., CATALINA_HOME/logs/catalina.out).

# Example log output excerpt
INFO [main] org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive [/path/to/tomcat/webapps/jenkins.war]
... many Jenkins startup logs ...
INFO [main] jenkins.install.SetupWizard.init Jenkins is fully up and running

Step 5: Access Jenkins

1. Open your web browser and navigate to http://<your_server_ip_or_hostname>:8080/jenkins (assuming Tomcat runs on port 8080).

2. If this is the first time running Jenkins, you will be guided through the initial setup wizard (unlocking Jenkins, installing plugins, creating admin user) as described in the Installation chapter, unless disabled.

Considerations

• JENKINS_HOME: When deployed in Tomcat, Jenkins typically creates its JENKINS_HOME directory within the user profile running Tomcat or as configured via context parameters/environment variables. You might need to explicitly set the JENKINS_HOME environment variable for the Tomcat process to control its location.
• Upgrades: To upgrade Jenkins, stop Tomcat, replace the jenkins.war file in webapps, delete the expanded jenkins directory within webapps (Tomcat usually handles this, but manual deletion ensures a clean deploy), and restart Tomcat.
• Resource Contention: Jenkins can be resource-intensive. Running it alongside other critical applications in the same Tomcat instance might lead to performance issues. Monitor resource usage carefully.