How to Run Jenkins in Docker with Persistent Data

You can run a local Jenkins controller in Docker with one container and a persistent volume. The volume is essential: Jenkins stores jobs, plugins, configuration, and credentials under /var/jenkins_home, which must survive replacement of the container.

This is a local learning setup, not a complete production deployment. Before starting, install Docker, use Linux-container mode on Docker Desktop, and check that docker version reports a reachable engine. See the Docker learning roadmap if containers are new to you.

Start Jenkins with a named volume

Run this command in PowerShell, Command Prompt, or a compatible terminal:

docker run -d --name jenkins-test -p 127.0.0.1:8080:8080 -v jenkins_home:/var/jenkins_home jenkins/jenkins:lts

• -d runs the container in the background.
• --name jenkins-test gives it a stable name.
• -p 127.0.0.1:8080:8080 publishes the web interface on this computer's loopback address.
• -v jenkins_home:/var/jenkins_home mounts a Docker-managed named volume at Jenkins' data directory.
• jenkins/jenkins:lts selects the Jenkins long-term-support image.

A named volume is not the same as a Windows folder such as D:jenkins. It avoids host-path and permission differences for this example. Do not reuse an existing volume containing important Jenkins data for an unrelated experiment.

The inbound-agent port is not published here because this first local setup does not require it. Agent connectivity should be configured deliberately for the deployment you build.

Check startup and unlock Jenkins

Use docker ps to check whether the container is running and docker logs jenkins-test to inspect startup. The first image download and initialization time depend on your connection and computer.

Open http://localhost:8080. For a new data volume, Jenkins displays its unlock page. Retrieve the initial password locally:

docker exec jenkins-test cat /var/jenkins_home/secrets/initialAdminPassword

Paste it into the administrator-password field and continue. Treat this password as a secret; do not post logs containing it. If the volume was already initialized, Jenkins may show its normal login instead of the first-run wizard.

Complete the setup wizard

1. Choose suggested plugins for a general starting point, or select the plugins your project requires.
2. Wait for installation to finish. If a plugin fails, read the error and check network or update-site access before retrying.
3. Create a named administrator account with a unique password and store it securely.
4. Confirm the Jenkins URL. For this local setup, use http://localhost:8080/.
5. Finish setup and verify that you can reach the dashboard and sign in with the new account.

The official Jenkins Docker guide covers installation and the setup wizard in more detail.

Stop, restart, and preserve the installation

docker stop jenkins-test
docker start jenkins-test

The web interface is unavailable while the container or Docker engine is stopped. Stopping does not erase the named volume. Keep the same volume when deliberately replacing the container, and back it up before upgrades. A volume provides persistence, not a backup.

Common startup problems

• Port already allocated: Use another unused host port, for example 127.0.0.1:8081:8080, and browse to port 8081.
• Container name already exists: Inspect the existing jenkins-test container. Start it if that is the installation you intended to use.
• Container exits: Read docker logs jenkins-test; check available memory, disk space, and volume access.
• Build cannot find Docker: Running Jenkins in a container does not automatically give its jobs a Docker engine. Design the build-agent environment separately.

Before exposing Jenkins beyond your computer, plan authentication, authorization, HTTPS, backups, updates, and agent isolation. Continue with CI/CD pipeline foundations after the local controller works.