CI/CD Deployment System

System Overview

Complete documentation for the CI/CD Deployment System

Quick Links

System Overview

What It Does

  • • Multi-repository support: Deploy any number of repositories
  • • Zero downtime: Docker-based deployments with no service interruption
  • • Automatic: Triggers on git pushes to main/master branches
  • • Universal: Works with any user, any directory structure

Key Benefits

  • • 🚀 Fast setup - One-command installation
  • • 🔄 Reliable - Automatic restarts and error handling
  • • 🌐 Universal - Works for any user or system
  • • 📦 Docker-based - Clean, isolated deployments
  • • 🛡️ Secure - Runs as non-root user

Architecture

Deployment Flow

Git Push
Git Provider
Webhook Server
Deploy Script
Docker

Input

  • • Git push to main/master branch
  • • Webhook payload from Git provider
  • • Repository name and branch info

Output

  • • Updated Docker containers
  • • Deployment logs
  • • Health status

Components

Webhook Server

Node.js application listening on port 9001

  • • Receives webhook requests
  • • Validates payload
  • • Triggers deployments
  • • Runs as systemd service

Deploy Scripts

Customizable per-repository deployment logic

  • • Auto-generated per project type
  • • Docker, Node.js, static sites
  • • Customizable commands
  • • Error handling

Systemd Service

Manages webhook server as a system service

  • • Automatic restarts
  • • Log management
  • • Process monitoring
  • • Boot-time startup

Docker

Container-based deployment platform

  • • Clean builds without cache
  • • Zero-downtime deployments
  • • Container isolation
  • • Health checks

Workflow

1️⃣

Developer Push

Git push to repository

→
2️⃣

Git Provider

Sends webhook

→
3️⃣

Webhook Server

Receives & validates

→
4️⃣

Deploy Script

Runs in repo directory

→
5️⃣

Docker

Builds & deploys

Detailed Process

  1. Developer pushes code to repository (main/master branch)
  2. Git provider (Gitea/GitHub) sends webhook to your server
  3. Webhook server receives the HTTP POST request with JSON payload
  4. Server validates the request and extracts repository name and branch
  5. Deploy script runs in the repository directory with git pull and Docker commands
  6. Docker builds the new version without cache and recreates containers
  7. Logs are written to both systemd journal and webhook log file

Key Features

Universal Installation

  • • Works for any username
  • • Configurable repository base directory
  • • No hardcoded paths or values
  • • Multi-OS support (Ubuntu/Debian/CentOS/Fedora/Arch)

Smart Project Detection

  • • Automatically detects project type
  • • Docker projects (docker-compose.yml)
  • • Node.js projects (package.json)
  • • Static sites (index.html)

Clean Builds

  • • Forces Docker rebuild without cache
  • • Pulls latest git changes before building
  • • Zero-downtime deployments
  • • Automatic container recreation

Robust Error Handling

  • • Continues deployment even if git pull fails
  • • Clear error messages and logging
  • • Automatic service restart on failure
  • • Graceful degradation

Installation Requirements

Server Requirements

  • • Linux (Ubuntu/Debian/CentOS/Fedora/Arch)
  • • Docker and Docker Compose
  • • Git (with SSH keys configured)
  • • Internet connection for downloads

What Gets Installed

  • • Node.js (if not present)
  • • Webhook server in ~/CI-CD/webhook-server/
  • • Systemd service webhook-multi-repo
  • • Log files in ~/CI-CD/webhook-server/webhook-multi-repo.log

Directory Structure 

~/CI-CD/webhook-server/
├── webhook-multi-repo.js    # Main webhook server
├── webhook-multi-repo.service # Systemd service file
└── webhook-multi-repo.log   # Log file

/path/to/your/repo/
└── deploy.sh                 # Deployment script (auto-generated)

Monitoring

Log Locations

  • • Webhook logs: ~/CI-CD/webhook-server/webhook-multi-repo.log
  • • System logs: sudo journalctl -u webhook-multi-repo -f

Health Checks

# Check service status
sudo systemctl status webhook-multi-repo

# Check recent activity
sudo journalctl -u webhook-multi-repo -n 20

# Monitor in real-time
sudo journalctl -u webhook-multi-repo -f

Advanced Usage

Custom Deploy Scripts

Edit the deploy.sh in your repository to customize:

  • • Build commands
  • • Environment variables
  • • Health checks
  • • Rollback procedures

Environment Variables

Set these in your deploy script:

  • • FORCE_CLEAN_BUILD=true - Force rebuild without cache
  • • Custom environment variables for your application

Multiple Environments

Create different webhook endpoints:

  • • http://server:9001/deploy - Production
  • • http://server:9002/deploy - Staging
  • • Configure different webhooks for each environment

Contributing

Found an issue or want to improve the system?

  1. 1. Test thoroughly - Make sure changes work across different setups
  2. 2. Document updates - Update relevant documentation
  3. 3. Submit pull request - Include clear description of changes

Support

  • • 📖 Troubleshooting guide - Check this first
  • • 🔧 Review logs - Check webhook and system logs
  • • 🧪 Test manually - Use curl to test webhook directly
  • • 📋 Provide details - Include error messages and system info when asking for help