DevSecOps-Lab/JENKINS_SETUP.md

Jenkins Setup Instructions

Prerequisites

1. Jenkins Installation

• Jenkins server with Docker support
• Required plugins:
  • Pipeline Plugin
  • Docker Pipeline Plugin
  • NodeJS Plugin
  • Git Plugin
  • Blue Ocean (optional, for better UI)
  • Coverage Plugin
  • Test Results Analyzer

2. Prerequisites on Jenkins Agent

The pipeline now uses a simplified approach that doesn't require specific tool configurations in Jenkins Global Tools. Instead, ensure these tools are available on your Jenkins agent:

Required Tools

# Node.js 18+ (Required)
node --version  # Should show v18.x.x or higher
npm --version   # Should be available with Node.js

# Docker (Optional - for containerization stages)
docker --version

# Git (Usually pre-installed)
git --version

# Curl (Usually pre-installed)
curl --version

Installation Commands for Jenkins Agent

# Install Node.js 18 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Docker (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y docker.io
sudo usermod -aG docker jenkins
sudo systemctl restart jenkins

# Install Trivy for security scanning (Optional)
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

3. Alternative: Using Jenkins Global Tools (Advanced)

If you prefer to use Jenkins Global Tools Configuration:

Node.js Tool Configuration

• Go to Manage Jenkins > Global Tool Configuration
• Name: nodejs (keep it simple)
• Version: NodeJS 18.x.x
• Install automatically: ✅

Then update the Jenkinsfile to include:

tools {
    nodejs 'nodejs'
}

3. Required Software on Jenkins Agent

# Install Trivy for security scanning
curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

# Install Docker Compose
curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

Pipeline Features

✅ Current Implementation

1. Multi-stage Pipeline: Organized stages for better visibility
2. Parallel Execution: Dependencies and tests run in parallel
3. Environment Detection: Different actions for different branches
4. Docker Integration: Build and scan container images
5. Security Scanning: Trivy integration for vulnerability scanning
6. Artifact Management: Archive build artifacts and reports
7. Integration Testing: Health checks and API testing
8. Branch-based Deployment: Different environments for different branches

🔄 Pipeline Stages

1. Checkout

• Clone repository
• Get Git commit information

2. Environment Info

• Display tool versions
• Build information

3. Install Dependencies (Parallel)

• Backend: npm ci
• Frontend: npm ci

4. Code Quality & Security (Parallel)

• Linting for both frontend and backend
• Security audit with npm audit

5. Test (Parallel)

• Backend unit tests
• Frontend tests with coverage

6. Build (Parallel)

• Build backend (if build script exists)
• Build frontend React application

7. Docker Build (Conditional)

• Build Docker images for both services
• Only on main/development/release branches

8. Docker Security Scan (Conditional)

• Scan images with Trivy
• Generate security reports

9. Integration Tests (Conditional)

• Start services with docker-compose
• Run health checks and API tests

10. Deployment (Branch-specific)

• Development: Auto-deploy to dev environment
• Release: Deploy to staging
• Main: Manual approval for production

Branch Strategy

🌿 Development Branch

• Automatic deployment to development environment
• Full testing pipeline
• Security scanning

🚀 Release Branch

• Deploy to staging environment
• Full security validation
• Performance testing ready

📦 Main Branch

• Production deployment with manual approval
• Complete security validation
• Artifact archival

Security Features

🔒 Implemented Security Checks

1. Dependency Scanning: npm audit for known vulnerabilities
2. Container Scanning: Trivy for Docker image vulnerabilities
3. Code Quality: Linting for code standards
4. Security Reports: JSON reports archived as artifacts

🛡️ Future Security Enhancements

• SAST (Static Application Security Testing)
• DAST (Dynamic Application Security Testing)
• Infrastructure as Code scanning
• Secret scanning
• License compliance checking

Environment Variables

Required Environment Variables

# Docker Registry (update in Jenkinsfile)
REGISTRY=your-docker-registry.com

# Notification settings
SLACK_WEBHOOK=your-slack-webhook
EMAIL_RECIPIENTS=team@company.com

Usage

1. Create Pipeline Job

1. Go to Jenkins Dashboard
2. Click "New Item"
3. Choose "Pipeline"
4. Configure SCM to point to your repository
5. Set script path to Jenkinsfile

2. Configure Webhooks

Add webhook in GitHub repository settings:

• URL: http://your-jenkins-server/github-webhook/
• Events: Push, Pull Request

3. First Run

• The pipeline will auto-detect the branch
• Development branch triggers full pipeline with dev deployment
• Main branch requires manual approval for production

Monitoring & Notifications

📊 Build Artifacts

• Test results and coverage reports
• Security scan reports
• Built frontend application
• Docker image information

📧 Notifications

• Success/failure notifications
• Security alert notifications
• Deployment confirmations

Troubleshooting

Common Issues

1. Tool not found errors

Tool type "nodejs" does not have an install of "NodeJS-18" configured

Solution:

• Current Jenkinsfile doesn't require tool configuration
• Ensure Node.js is installed on Jenkins agent: node --version
• If needed, install with: curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs

2. Node.js not available

Node.js is not available. Please install Node.js 18+ on the Jenkins agent.

Solution: Install Node.js on the Jenkins agent machine:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

2. Missing FilePath context in post actions

Required context class hudson.FilePath is missing

Solution: Already fixed in current Jenkinsfile with proper script blocks

3. Docker permission denied

docker: Got permission denied while trying to connect to the Docker daemon socket

Solution: Add Jenkins user to docker group:

sudo usermod -aG docker jenkins
sudo systemctl restart jenkins

4. Trivy not found

trivy: command not found

Solution: Install Trivy on Jenkins agent:

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin

5. Port conflicts during integration tests

curl: (7) Failed to connect to localhost port 3001

Solution: Ensure ports 3000, 3001, 80 are available on Jenkins agent

Debug Commands

# Check Jenkins agent tools
which node npm docker trivy

# Verify Docker access
docker ps

# Test repository access
git clone https://github.com/K0ngS3ng/DevSecOpsApp.git

# Check tool configurations in Jenkins
curl -u admin:password http://jenkins-url/manage/configureTools/

Pipeline Configuration Examples

Minimal Configuration (No Docker)

If Docker is not available, the pipeline will gracefully skip Docker-related stages:

// Pipeline will automatically skip Docker stages if tools are not available
// Error handling is built-in for all Docker operations

Custom Tool Names

If you have different tool names configured:

tools {
    nodejs 'Node18'        // Your custom NodeJS name
    dockerTool 'MyDocker'  // Your custom Docker name
}

Next Steps

1. Configure actual deployment environments
2. Add more comprehensive tests
3. Integrate with monitoring tools
4. Set up notification channels
5. Add performance testing stages