Seamless Jenkins Migration Across Platforms Using Docker Compose

Rohil Mogal — Tue, 06 May 2025 04:52:08 +0000

Migrate Jenkins from Linux VM to macOS (Plain Installation)

Step 1: Jenkins Backup

Find your current JENKINS_HOME
(If unsure, you can check it inside Jenkins UI → Manage Jenkins → System Information → search for JENKINS_HOME.) e.g. /var/lib/jenkins
Backup Jenkins home

sudo tar -czvf jenkins_backup.tar.gz /var/lib/jenkins

Step 2: Transfer the Backup to Your macOS Machine

Now this really depends on how you want to copy this data. Either SCP, USB, etc. I used traditional USB stick to copy this data to my Mac device.

Step 3: Install Jenkins on macOS

brew install jenkins-lts

brew services start jenkins-lts

By default, Jenkins will use /Users//.jenkins as the JENKINS_HOME.

I faced an issue where Jenkins dint really start as it was not able to discover JAVA_HOME env upon running above command. Best way to get rid of this was to run this without services command

jenkins-lts

That the entire 2 words command to start Jenkins with all the env variables preserved and available for jenkins to use.

Step 4: Replace macOS Jenkins Data with the Backup

Stop Jenkins on macOS:

brew services stop jenkins-lts

OR
Command + C to Stop if you ran

jenkins-lts

Extract the backup and replace Jenkins home

cd ~
tar -xzvf jenkins_backup.tar.gz
mv ~/.jenkins ~/.jenkins.backup   # Backup current empty Jenkins home
mv var/lib/jenkins ~/.jenkins     # Use Linux Jenkins data

Fix permissions

sudo chown -R $(whoami) ~/.jenkins

Start Jenkins again

brew services start jenkins-lts 
#OR
jenkins-lts

Step 5: Verify

Visit http://localhost:8080 on your browser.

Restore Jenkins from Backup using Docker Compose

Step 1: Jenkins Backup

Find your current JENKINS_HOME
(If unsure, you can check it inside Jenkins UI → Manage Jenkins → System Information → search for JENKINS_HOME.) e.g. /var/lib/jenkins
Backup Jenkins home

sudo tar -czvf jenkins_backup.tar.gz /var/lib/jenkins

Step 2: Transfer the Backup to Your macOS Machine

Now this really depends on how you want to copy this data. Either SCP, USB, etc. I used traditional USB stick to copy this data to my Mac device.

Step 3: Extract Jenkins Backup

Create a working directory in your choice of OS (Linux, MacOS)

mkdir ${PWD}/jenkins_home
tar -xzvf jenkins_backup.tar.gz -C ${PWD}/jenkins_home --strip-components=1

Step 4: Create the docker-compose.yml File

version: '3'

services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - ./jenkins_home:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock  # Optional: if Jenkins needs to run Docker
    restart: unless-stopped

Step 5: Start Jenkins with Docker Compose

docker-compose up -d

Step 6: Verify

Visit http://localhost:8080 on your browser.

Known Issues - Admin Login Issue

Even after doing everything correctly, you might not able to login with admin or user credentials even though its correct and worked on earlier. Reason being whenever you create a user creds in Jenkins it encrypt it and might not be able to decrypt it. Fastest way to recover from this

Solution 1: Delete Admin User

rm -rf jenkins_home/users/admin

Restart Jenkins after this and it will promt to create new admin user

Solution 2: Alter Admin Hashed Password

Ideally all the users are stored in /var/lib/jenkins/users/
You might see a folder with admin prefix. e.g. admin_13844028951691835221
Locate config.xml file inside the admin folder and change the below line

<hudson.security.HudsonPrivateSecurityRealm_-Details>
      <passwordHash>#jbcrypt:$2a$10$1me96JIU604I.q19wwgJTeqNJUKwZAuP11brUjk6VJTBfRuAYixxe</passwordHash>
    </hudson.security.HudsonPrivateSecurityRealm_-Details>

Create a new hash with the password you desire. You can use the below link to create a hash password
https://bcrypt-generator.com/

Replace the old hash value with the new hash you just created. Restart Jenkins and try to login with new password.

Just like Magic !!!! (Yeah I know, petty tricks but it works)

DEV Community: Rohil Mogal

Seamless Jenkins Migration Across Platforms Using Docker Compose

Migrate Jenkins from Linux VM to macOS (Plain Installation)

Restore Jenkins from Backup using Docker Compose

Known Issues - Admin Login Issue