Jenkins CI/CD Pipeline for Multi-Environment Deployment

A robust Jenkins pipeline configuration for automated deployment across multiple environments (Development, Staging, Production) with Docker containerization and health monitoring.

🚀 Features

• Multi-Environment Support: Automated deployment to dev, staging, and production environments
• Branch-Based Deployment: Different environments triggered by specific branch patterns
• Docker Integration: Containerized application with automated image building and registry push
• Health Monitoring: Container status validation after deployment
• Notification System: Optional Mattermost integration for build notifications
• Security First: All sensitive data managed through Jenkins credentials
• Rollback Support: Deployment history and easy rollback capabilities

📋 Prerequisites

Jenkins Plugins Required

• SSH Agent Plugin
• Mattermost Plugin (optional, for notifications)
• Docker Pipeline Plugin
• Git Plugin
• Credentials Plugin

Server Requirements

• Docker and Docker Compose installed on target servers
• SSH access configured for deployment user
• Network access to Docker registry
• Proper firewall configuration

⚙️ Configuration

1. Jenkins Credentials Setup

Configure the following credentials in Jenkins (Manage Jenkins → Credentials):

Docker Registry Access:

• docker-registry-credentials (Username/Password)

Server Access for each environment:

• {env}-ssh-key (SSH Private Key)
• {env}-remote-user (Secret Text)
• {env}-server-address (Secret Text)
• {env}-deployment-path (Secret Text)

Where {env} = dev, stage, prod

Optional Notifications:

• mattermost-webhook-url (Secret Text)
• mattermost-channel (Secret Text)

📖 Detailed setup instructions: See jenkins-config-example.md

2. Pipeline Parameters

When running the pipeline, you can customize:

Parameter	Description	Default
IMAGE_NAME	Docker image name	your-app-name
DOCKERFILE	Dockerfile path	Dockerfile
CONTAINER_NAMES	Containers to monitor	app-1, service-1, worker-1
CONTAINER_SERVICES	Services to restart	app, service, worker

🌳 Branch Strategy

Branch Pattern	Environment	Image Tag	Manual Approval
main, master	Production	prod	Required
stage, staging	Staging	stage	Not required
dev, develop, development	Development	latest	Not required
Feature branches	Development	feature-{branch}	Not required

🏗️ Pipeline Stages

1. Gather Information

• Extracts Git commit details (hash, author, message)
• Used for tracking and notifications

2. Prepare Environment

• Determines target environment based on branch
• Sets appropriate configuration variables
• Validates environment setup

3. Docker Build and Push

• Builds Docker image with environment-specific tag
• Pushes to configured Docker registry
• Cleans up local images for security

4. Deploy

• Connects to target server via SSH
• Auto-detects Docker Compose command
• Pulls latest image and recreates services
• Handles production approval workflow

5. Health Check

• Validates container status post-deployment
• Fails pipeline if containers are unhealthy
• Provides detailed status reporting

🛠️ Usage

Development Deployment

git checkout dev
git add .
git commit -m "Development changes"
git push origin dev

→ Automatically deploys to development environment

Staging Deployment

git checkout stage
git add .
git commit -m "Staging release"
git push origin stage

→ Automatically deploys to staging environment

Production Deployment

git checkout main
git add .
git commit -m "Production release"
git push origin main

→ Requires manual approval before deployment

🐳 Docker Configuration

Example docker-compose.yml

version: '3.8'

services:
  app:
    image: ${DOCKER_USER}/your-app:${IMAGE_TAG:-latest}
    container_name: app-1
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production

  service:
    image: ${DOCKER_USER}/your-app:${IMAGE_TAG:-latest}
    container_name: service-1
    restart: unless-stopped

  worker:
    image: ${DOCKER_USER}/your-app:${IMAGE_TAG:-latest}  
    container_name: worker-1
    restart: unless-stopped

📊 Monitoring & Notifications

Container Health Monitoring

The pipeline automatically checks container status:

• ✅ Up: Container running normally
• ❌ Restarting: Pipeline fails, requires investigation
• ❌ Exited: Pipeline fails, check logs
• ❌ Not Found: Pipeline fails, verify container names

Mattermost Notifications (Optional)

Automated notifications include:

• Build status (Success/Failed)
• Environment and branch information
• Git commit details
• Direct link to Jenkins build
• Container deployment status

🔐 Security Features

• Credential Management: All secrets stored in Jenkins credentials store
• SSH Key Authentication: No password-based access
• Image Cleanup: Local Docker images removed after push
• Network Security: SSH timeout and connection validation
• Audit Trail: Complete deployment history and logging

🚨 Troubleshooting

Common Issues

Build Fails at Docker Push

• Verify Docker registry credentials
• Check network connectivity to registry

SSH Connection Failed

• Validate SSH key credentials in Jenkins
• Test manual SSH connection to target server
• Check server firewall rules

Container Health Check Failed

• Review container logs: docker logs container-name
• Verify docker-compose.yml configuration
• Check if image exists in registry

Production Approval Timeout

• Look for pending input in Jenkins UI
• Configure input timeout in pipeline if needed

Manual Recovery Commands

# SSH to problematic server
ssh user@server-address

# Check container status
docker ps -a

# View container logs  
docker logs container-name

# Manual service restart
cd /path/to/deployment
docker-compose restart service-name

# Full redeployment
docker-compose down
docker-compose pull  
docker-compose up -d --force-recreate

📈 Best Practices

Development Workflow

1. Feature Development: Work on feature branches
2. Testing: Merge to dev branch for development testing
3. Staging: Merge to stage branch for pre-production validation
4. Production: Merge to main branch for production deployment

Deployment Safety

• Always test in lower environments first
• Use descriptive commit messages (appear in notifications)
• Monitor deployment notifications in communication channels
• Keep deployment rollback procedures documented

Security

• Rotate SSH keys regularly
• Use least-privilege access on servers
• Scan Docker images for vulnerabilities
• Review Jenkins security settings periodically

📚 Additional Documentation

• jenkins-config-example.md - Detailed setup instructions
• Docker Compose Best Practices
• Jenkins Security Best Practices

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Update documentation as needed
4. Test changes in development environment
5. Submit pull request with detailed description

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues and questions:

1. Check the troubleshooting section above
2. Review Jenkins build logs for specific errors
3. Validate server and container status manually
4. Open an issue with detailed error information and environment details