Jenkins Configuration Guide

Windows + Linux installation, Java, Git, Maven, credentials, pipelines, webhooks, deployment and troubleshooting

1. Jenkins Configuration Overview

Jenkins is commonly used as a CI/CD server to check out source code, build applications, run tests, publish artifacts or container images, and deploy applications.

JenkinsJavaGit MavenDockerSSH PipelineWebhook
Typical flow: Developer → Git → Webhook → Jenkins → Checkout → Build → Test → Package → Artifact/Docker → Deploy → Health Check
ComponentPurpose
JenkinsCI/CD orchestration
JavaRuntime required by Jenkins
GitSource-code checkout
MavenBuild Spring Boot/Java applications
DockerContainer build/run when required
SSHRemote Linux deployment
NginxOptional reverse proxy and HTTPS endpoint
Java compatibility: The required Java version depends on the Jenkins release. Verify the supported Java versions for the Jenkins version you are installing.

2. Jenkins Installation — Windows

Step 1 — Install Java

Install a JDK supported by your Jenkins release, then verify:

java -version
where java

Step 2 — Configure JAVA_HOME

JAVA_HOME=C:\Program Files\Java\jdk-17

Add %JAVA_HOME%\bin to PATH and verify:

echo %JAVA_HOME%
java -version

Step 3 — Install Jenkins

Install Jenkins using the official Windows installer. During installation, Jenkins can be configured as a Windows service.

Step 4 — Check Jenkins service

services.msc

Find the Jenkins service.

Step 5 — Start, stop and restart Jenkins

net start jenkins
net stop jenkins

net stop jenkins
net start jenkins

Step 6 — Check port 8080

netstat -ano | findstr :8080
curl http://localhost:8080

Step 7 — Initial administrator password

A common Windows Jenkins home location is:

C:\ProgramData\Jenkins\.jenkins\secrets\initialAdminPassword

Confirm the actual JENKINS_HOME for your installation before relying on this path.

Step 8 — Open Jenkins

http://localhost:8080

3. Jenkins Installation — Linux

Step 1 — Check Linux version

cat /etc/os-release

Step 2 — Update packages

Ubuntu/Debian:

sudo apt update
sudo apt upgrade -y

RHEL/Rocky/AlmaLinux:

sudo dnf update -y

Step 3 — Install supported Java

Example for Ubuntu:

sudo apt install -y openjdk-17-jdk
java -version

Step 4 — Find JAVA_HOME

readlink -f $(which java)

Example JDK directory:

/usr/lib/jvm/java-17-openjdk-amd64

For a persistent setting:

sudo nano /etc/environment
JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"

Reload:

source /etc/environment
echo $JAVA_HOME
java -version

Step 5 — Install Jenkins

Configure the official Jenkins repository for your Linux distribution, then install Jenkins. On Debian/Ubuntu systems:

sudo apt update
sudo apt install -y jenkins

Step 6 — Enable and start

sudo systemctl enable jenkins
sudo systemctl start jenkins

Step 7 — Check status and logs

sudo systemctl status jenkins
sudo journalctl -u jenkins -f

Step 8 — Check port

sudo ss -lntp | grep 8080
curl http://localhost:8080

Step 9 — Initial password

sudo cat /var/lib/jenkins/secrets/initialAdminPassword
If your Jenkins home directory differs, inspect the Jenkins service configuration rather than assuming /var/lib/jenkins.

4. Jenkins Initial Configuration

1. Open Jenkins: http://localhost:8080 or http://SERVER-IP:8080.
2. Enter the initial administrator password.
3. Install recommended plugins initially.
4. Create a permanent administrator account.
5. Configure the Jenkins URL, for example https://jenkins.example.com/.
6. Verify Jenkins Home and service configuration.
Linux:
echo $JENKINS_HOME
sudo systemctl cat jenkins

Windows:
echo %JENKINS_HOME%

5. Configure JDK, Git and Maven

5.1 JDK

Use Manage Jenkins → Tools → JDK installations and configure the JDK required by your jobs.

5.2 Git

Windows:
git --version
where git

Linux:
git --version
which git

Configure Git under Manage Jenkins → Tools → Git installations if required.

5.3 Maven

mvn -version

Windows:
where mvn

Linux:
which mvn

Configure Maven under Manage Jenkins → Tools → Maven installations.

Recommended: Use the Maven Wrapper (./mvnw on Linux and mvnw.cmd on Windows) for reproducible project builds.

6. Configure Git Repository Access

Option A — SSH

ssh-keygen -t ed25519 -C "jenkins-ci"
cat ~/.ssh/id_ed25519.pub
ssh -T git@github.com

Add the public key to your Git provider as an appropriate deploy key/service credential.

Option B — HTTPS + Token

Create a Jenkins credential using a Personal Access Token or equivalent token. Do not store a normal account password in the Jenkinsfile.

Navigate to:

Manage Jenkins → Credentials → System → Global credentials

Pipeline checkout example

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                git branch: 'main',
                    credentialsId: 'git-credentials',
                    url: 'git@github.com:organization/project.git'
            }
        }
    }
}

7. Jenkins Credentials

Credential TypeTypical Use
Username + PasswordLegacy systems and selected registries
SSH Username with Private KeyGit SSH and Linux deployment
Secret TextAPI tokens and application secrets
Secret FileConfiguration files/certificates

Example credential IDs

git-credentials
docker-registry
linux-deploy-key
nexus-credentials
sonarqube-token
Never hard-code passwords, private keys, API tokens or database credentials in a Jenkinsfile.

8. Create Jenkins Pipeline

8.1 Create Pipeline job

  1. Select New Item.
  2. Enter a job name.
  3. Select Pipeline.
  4. Click OK.
  5. Configure the Pipeline definition.

8.2 Linux Spring Boot Maven pipeline

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                git branch: 'main',
                    credentialsId: 'git-credentials',
                    url: 'git@github.com:organization/frt-test-series.git'
            }
        }

        stage('Build') {
            steps {
                sh './mvnw clean package -DskipTests'
            }
        }

        stage('Test') {
            steps {
                sh './mvnw test'
            }
        }

        stage('Archive') {
            steps {
                archiveArtifacts artifacts: 'target/*.jar',
                                 fingerprint: true
            }
        }
    }
}

8.3 Windows pipeline

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                git branch: 'main',
                    credentialsId: 'git-credentials',
                    url: 'https://github.com/organization/project.git'
            }
        }

        stage('Build') {
            steps {
                bat 'mvnw.cmd clean package -DskipTests'
            }
        }

        stage('Test') {
            steps {
                bat 'mvnw.cmd test'
            }
        }

        stage('Archive') {
            steps {
                archiveArtifacts artifacts: 'target\\*.jar',
                                 fingerprint: true
            }
        }
    }
}

9. Git Webhook Configuration

Step 1 — Jenkins job

Configure the appropriate SCM webhook trigger, such as the GitHub hook trigger provided by the installed GitHub integration.

Step 2 — Git provider

Configure a webhook in the repository settings using the Jenkins endpoint appropriate to your integration. A common GitHub endpoint is:

https://jenkins.example.com/github-webhook/

Step 3 — Test

  1. Push a commit.
  2. Check webhook delivery status.
  3. Check Jenkins build history.
  4. Open Console Output.
The Jenkins endpoint must be reachable by the Git provider. Secure the endpoint with HTTPS, authentication/authorization controls and appropriate network restrictions.

10. Linux Deployment Using Jenkins + SSH

Step 1 — Create deployment user

sudo useradd -m -s /bin/bash deployuser

Step 2 — Generate deployment key on Jenkins agent

ssh-keygen -t ed25519 -C "jenkins-deploy"

Step 3 — Copy public key to target server

ssh-copy-id deployuser@SERVER_IP

Step 4 — Test

ssh deployuser@SERVER_IP

Step 5 — Add private key to Jenkins

Go to:

Manage Jenkins → Credentials → System → Global credentials

Select SSH Username with private key.

Step 6 — Deployment pipeline example

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh './mvnw clean package -DskipTests'
            }
        }

        stage('Deploy') {
            steps {
                sshagent(credentials: ['linux-deploy-key']) {
                    sh '''
                        scp target/*.jar deployuser@SERVER_IP:/opt/apps/myapp/
                        ssh deployuser@SERVER_IP 'sudo systemctl restart myapp'
                    '''
                }
            }
        }
    }
}
Do not give Jenkins unrestricted sudo access. Configure narrowly scoped sudo permissions for only the deployment operations required.

11. Deploy Spring Boot Application as systemd Service

Create service

sudo nano /etc/systemd/system/myapp.service
[Unit]
Description=My Spring Boot Application
After=network.target

[Service]
User=deployuser
WorkingDirectory=/opt/apps/myapp
ExecStart=/usr/bin/java -jar /opt/apps/myapp/myapp.jar
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp

Restart after Jenkins deployment

sudo systemctl daemon-reload
sudo systemctl restart myapp
sudo systemctl status myapp --no-pager

Application logs

sudo journalctl -u myapp -f

12. Jenkins + Docker

Verify Docker

Linux:
docker --version
sudo systemctl status docker

Windows:
docker --version

Linux Jenkins access to Docker

sudo usermod -aG docker jenkins
sudo systemctl restart jenkins
Membership in the Docker group can provide powerful host-level privileges. Treat Jenkins as a highly privileged service.

Build and tag image

docker build -t frt-test-series:${BUILD_NUMBER} .
docker tag frt-test-series:${BUILD_NUMBER} REGISTRY_HOST/frt-test-series:${BUILD_NUMBER}

Push image

docker login REGISTRY_HOST
docker push REGISTRY_HOST/frt-test-series:${BUILD_NUMBER}

13. Jenkins Behind Nginx on Linux

Example Nginx configuration

server {
    listen 80;
    server_name jenkins.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Validate and reload

sudo nginx -t
sudo systemctl reload nginx

Configure public Jenkins URL

https://jenkins.example.com/
For production, use HTTPS with a valid certificate and ensure the Jenkins public URL matches the URL users and webhooks actually use.

14. Jenkins Service Management

Linux

sudo systemctl status jenkins
sudo systemctl start jenkins
sudo systemctl stop jenkins
sudo systemctl restart jenkins
sudo systemctl enable jenkins
sudo journalctl -u jenkins -f

Windows

net start jenkins
net stop jenkins
sc query jenkins
services.msc

Port diagnostics

Linux:
sudo ss -lntp | grep 8080

Windows:
netstat -ano | findstr :8080

15. Jenkins Security Configuration

AreaRecommendation
AuthenticationUse strong administrator accounts and enterprise identity integration where available.
AuthorizationUse role-based or matrix-based permissions appropriate to your team.
CSRFKeep Jenkins security protections enabled.
CredentialsUse Jenkins Credentials or an external secrets manager.
PluginsUpdate plugins and remove unused plugins.
NetworkRestrict access with firewall, security groups or VPN where appropriate.
AgentsUse dedicated agents for specialized or high-risk builds.
BackupsBack up Jenkins configuration and job definitions.

16. Troubleshooting

Jenkins does not start — Linux

sudo systemctl status jenkins
sudo journalctl -u jenkins -n 200 --no-pager
java -version

Port 8080 already in use

Linux:
sudo lsof -i :8080
sudo ss -lntp | grep :8080

Windows:
netstat -ano | findstr :8080
tasklist /FI "PID eq PID_NUMBER"

Git clone fails

git --version
ssh -T git@github.com

Maven not found

mvn -version

Linux:
which mvn

Windows:
where mvn

Use Maven Wrapper when practical:

Linux:
./mvnw clean package

Windows:
mvnw.cmd clean package

Docker permission failure

sudo systemctl status docker
sudo -u jenkins docker ps
groups jenkins

Webhook does not trigger build

17. Jenkins Backup

Linux example

sudo systemctl stop jenkins
sudo tar -czf jenkins-home-backup.tar.gz /var/lib/jenkins
sudo systemctl start jenkins

Windows PowerShell example

Compress-Archive `
  -Path "C:\ProgramData\Jenkins\.jenkins\*" `
  -DestinationPath "D:\Backup\jenkins-home-backup.zip"
Confirm the actual Jenkins home directory before backing it up. For large/critical installations, use a tested Jenkins backup strategy.

18. Complete Jenkins Configuration Checklist

Windows

Linux

19. Recommended CI/CD Flow for a Spring Boot Microservices Project

Developer
   |
   | git push
   v
GitHub / GitLab
   |
   | Webhook
   v
Jenkins
   |
   +-- Checkout source
   |
   +-- Validate Java / Maven
   |
   +-- mvn clean
   |
   +-- mvn test
   |
   +-- mvn package
   |
   +-- Static analysis (optional)
   |
   +-- Build Docker image (optional)
   |
   +-- Push image / Nexus / Artifactory
   |
   +-- Deploy to DEV
   |
   +-- Health check
   |
   +-- QA approval
   |
   +-- Deploy to QA
   |
   +-- Production approval
   |
   +-- Deploy to Production
   |
   +-- Health verification
Recommended architecture: Jenkins handles CI/CD orchestration; Git handles source control; Maven builds Java applications; Nexus/Artifactory stores artifacts; Docker/Helm can package deployments; systemd/SSH or Kubernetes can perform deployment depending on the target environment.

20. Quick Command Reference

Linux

# Java
java -version

# Jenkins
sudo systemctl status jenkins
sudo systemctl restart jenkins
sudo journalctl -u jenkins -f

# Port
sudo ss -lntp | grep 8080

# Git
git --version

# Maven
mvn -version

# Docker
docker --version
sudo systemctl status docker

# Initial password
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

Windows

REM Java
java -version

REM Jenkins service
net start jenkins
net stop jenkins
sc query jenkins

REM Port
netstat -ano | findstr :8080

REM Git
git --version

REM Maven
mvn -version

REM Docker
docker --version

21. Final Recommended Setup

LayerRecommended Configuration
Source ControlGitHub/GitLab/Bitbucket
CI ServerJenkins on Linux for production
RuntimeJenkins-supported JDK
BuildMaven Wrapper / Maven
CredentialsJenkins Credentials / external secret manager
ArtifactNexus / Artifactory
ContainerDocker where required
Deploymentsystemd/SSH, Docker, Kubernetes or Helm
Reverse ProxyNginx + HTTPS
MonitoringJenkins and application monitoring/logging
BackupJENKINS_HOME + tested backup strategy
Important: Jenkins and its plugins change over time. Always verify the Jenkins release's supported Java version and use the official Jenkins installation instructions for the exact repository/package commands.