If Jenkins had a secret closet it would be called JENKINS_HOME. This is the filesystem location where Jenkins keeps its config plugins jobs build artifacts and logs. Get this wrong and you will learn what panic feels like after a plugin update.
Where Jenkins stores things by default
Default locations depend on how you installed Jenkins and how much you like surprises.
- Package installs on Linux usually use
/var/lib/jenkins
- Single user installs often create
~/.jenkins
in the user home - Containers have an internal path that you should map to a host mount so your data does not evaporate when the container dies
Quick examples that do not require a magic wand
Temporary shell session
export JENKINS_HOME=/var/lib/jenkins
Make it persistent under systemd
Create an override so the service always starts with the correct environment. Run this and edit the file that opens.
systemctl edit jenkins
Add these lines to the override file and save.
[Service]
Environment=JENKINS_HOME=/var/lib/jenkins
Then reload systemd and restart Jenkins so it reads the new path.
systemctl daemon-reload
systemctl restart jenkins
Docker run example that keeps your data
Use an explicit environment variable and a bind mount so your builds survive container churn.
docker run -d \
-e JENKINS_HOME=/var/jenkins_home \
--mount type=bind,source=/host/jenkins_home,target=/var/jenkins_home \
jenkins/jenkins:lts
Permissions and moving JENKINS_HOME
Permissions matter more than charm. The user that runs the Jenkins process must own the directory and have read write access. If you are using the packaged service that user is usually named jenkins. Set ownership and permissions before starting Jenkins on the new path.
chown -R jenkins.jenkins /var/lib/jenkins
chmod -R 750 /var/lib/jenkins
To move an existing JENKINS_HOME stop Jenkins copy the data preserve ownership and restart. Using rsync or cp with archive mode will keep timestamps permissions and links intact.
systemctl stop jenkins
rsync -a /old/jenkins_home/ /var/lib/jenkins/
chown -R jenkins.jenkins /var/lib/jenkins
systemctl start jenkins
Which environment setting wins
Environment variables that are part of the process beat casual exports you typed into a shell after the service started. That means your systemd unit or Docker run command determines the actual JENKINS_HOME used by the running process. Do not rely on transient shell exports if you want predictable storage.
Backups and safety tips
- Back up JENKINS_HOME before you tinker with plugins or upgrades. A simple tar or rsync backup is a lifesaver.
- Pick a stable path outside temporary directories and outside user home folders that might disappear.
- Use an explicit environment entry in systemd or explicit options in your container runtime rather than hoping for the best.
- Test restores on a separate instance before you trust them in production.
Final words for the brave
JENKINS_HOME is not mystical. Treat it like the single source of truth for your Jenkins instance. Set it explicitly mount it from a host for containers keep permissions tidy and back it up. Do that and you will sleep slightly better when Jenkins decides to be dramatic.