How to Change Jenkins Home Directory?

Jenkins is a popular automation server that helps automate tasks in the software development process. The Jenkins Home Directory, also known as JENKINS_HOME, is the location where all configuration files, plugins, jobs, and other essential files are stored.

This directory plays a significant role in maintaining the stability and performance of the Jenkins environment. There may be situations where you need to change the Jenkins Home Directory location, such as moving to a larger disk, relocating to a different server, or organizing your file system better.

Preparing to Change Jenkins Home Directory

Understanding the Current Jenkins Home Directory Location

Before changing the Jenkins Home Directory, it is important to identify its current location. You can find this information in several ways:

• Jenkins Dashboard: Go to "Manage Jenkins" ? "System Information" and look for the JENKINS_HOME variable.

• Configuration file: Check /etc/default/jenkins (Linux) or C:\Program Files (x86)\Jenkins\jenkins.xml (Windows).

• Environment variables: Run echo $JENKINS_HOME in your terminal.

Creating a New Directory for Jenkins Home

Create a new directory in a location with sufficient storage space. It's recommended to create this directory outside of user-specific directories to avoid permission issues later.

sudo mkdir -p /opt/jenkins_home_new
sudo chown jenkins:jenkins /opt/jenkins_home_new

Changing the Jenkins Home Directory Location

Step 1: Stop the Jenkins Service

First, stop the Jenkins service to prevent file corruption during the move:

sudo systemctl stop jenkins

For Windows systems:

net stop jenkins

Step 2: Move Jenkins Home Directory Contents

Copy all contents from the current Jenkins home to the new location. Using rsync ensures all file permissions and timestamps are preserved:

sudo rsync -av /var/lib/jenkins/ /opt/jenkins_home_new/

Alternatively, you can use the cp command:

sudo cp -R /var/lib/jenkins/* /opt/jenkins_home_new/

Step 3: Update the Configuration File

Edit the Jenkins configuration file to point to the new directory location:

sudo vim /etc/default/jenkins

Find the JENKINS_HOME variable and update it:

JENKINS_HOME=/opt/jenkins_home_new

For systemd-based systems, you may also need to update the service file:

sudo vim /etc/systemd/system/jenkins.service

Step 4: Set Correct Permissions

Ensure the new directory has the correct ownership and permissions:

sudo chown -R jenkins:jenkins /opt/jenkins_home_new
sudo chmod -R 755 /opt/jenkins_home_new

Verifying and Restarting Jenkins Service

Verification Steps

Before restarting Jenkins, verify that all files have been moved successfully:

ls -la /opt/jenkins_home_new
# Check for key files: config.xml, jobs/, plugins/, secrets/

Starting Jenkins with New Configuration

Reload the systemd configuration and start Jenkins:

sudo systemctl daemon-reload
sudo systemctl start jenkins
sudo systemctl status jenkins

Verify Jenkins is Running

Check that Jenkins is running properly by:

• Accessing the Jenkins web interface

• Verifying all jobs are visible on the dashboard

• Checking system information shows the new JENKINS_HOME path

Troubleshooting Common Issues

Jenkins Service Fails to Start

If Jenkins fails to start, check the service logs:

sudo journalctl -u jenkins -f

Common causes include:

• Incorrect permissions: Ensure the jenkins user owns the new directory

• Wrong path: Verify the JENKINS_HOME path in the configuration file

• Missing files: Check that all files were copied successfully

Jobs Not Showing Up

If jobs are missing from the dashboard:

• Verify the jobs/ directory exists in the new location

• Check file permissions on individual job directories

• Reload Jenkins configuration from disk

Plugin Issues

If plugins are not working correctly:

• Ensure the plugins/ directory was copied completely

• Check that plugin files have correct permissions

• Consider reinstalling problematic plugins

Conclusion

Changing the Jenkins Home Directory is a straightforward process when done systematically. The key steps involve stopping Jenkins, moving the directory contents, updating configuration files, and verifying everything works correctly. Proper file permissions and complete data transfer are crucial for a successful migration.