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
```bash
# 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
```bash
# 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:
```groovy
tools {
    nodejs 'nodejs'
}
```

### 3. Required Software on Jenkins Agent
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
sudo usermod -aG docker jenkins
sudo systemctl restart jenkins
```

#### 4. **Trivy not found**
```
trivy: command not found
```
**Solution**: Install Trivy on Jenkins agent:
```bash
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
```bash
# 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:
```groovy
// 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:
```groovy
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