RIT-nexus/GITEA_WEBHOOK_CICD_DOCUMENTATION.md

🚀 Gitea Webhook Automated CI/CD Pipeline Documentation

Project: RIT Freshers Hub (RIT-nexus)
Server: Ubuntu 24.04 VPS (129.121.126.66)
Architecture: Zero-Timeout Asynchronous Webhook & Systemd Microservices

---

📌 1. High-Level Architecture & Interaction Flow

The CI/CD pipeline automatically deploys code from your local machine to the production VPS server whenever a commit is pushed to the main branch on Gitea.

sequenceDiagram
    autonumber
    actor Developer as 💻 Developer PC
    participant Gitea as 🐙 Gitea Repository
    participant Listener as 🐍 Webhook Listener (Port 9000)
    participant Script as 📜 deploy.sh Engine
    participant Services as ⚙️ Systemd & Nginx

    Developer->>Gitea: git push origin main
    Note over Gitea: Git commit received (e.g. ef47a65)
    Gitea->>Listener: HTTP POST http://129.121.126.66:9000/hooks/deploy
    Note over Listener: Detaches process & responds instantly
    Listener-->>Gitea: HTTP 200 OK (0.001s response)
    Listener->>Script: Spawns /var/www/freshers-hub/deploy.sh
    
    rect rgb(240, 245, 255)
        Note over Script: 1. git fetch origin main && git reset --hard origin/main
        Note over Script: 2. npm install && npm run build
        Note over Script: 3. cd chatbot-service && go build -o chatbot-service main.go
        Note over Script: 4. cd backend && ./mvnw clean package -DskipTests
        Script->>Services: systemctl restart springboot chatbot telegram-bot nginx
    end
    
    Script-->>Script: Write log output to /var/log/deploy.log

---

⚙️ 2. Detailed Component Breakdown

Component 1: Local Developer Environment (git push)

• Role: Where you write code, test locally, and initiate deployments.
• Trigger Action:

  git commit -m "feat(topic): your changes"
  git push origin main
  

• Target Remote: https://git.rit-services.in/ShanmugaKrishnanSM/RIT-nexus.git

---

Component 2: Gitea Remote Repository (git.rit-services.in)

• Role: Code hosting, version control, and event trigger dispatcher.
• Webhook Configuration:
  • Location: Repository ➔ Settings ➔ Webhooks
  • Target URL: http://129.121.126.66:9000/hooks/deploy
  • HTTP Method: POST
  • Content Type: application/json
  • Trigger Event: Push Events on main branch.

---

Component 3: VPS Webhook Listener Service (webhook.service & webhook_server.py)

• Role: A lightweight Python HTTP server listening on port 9000.
• Zero-Timeout Asynchronous Pattern:
  Standard Webhooks fail if the build takes longer than Gitea's 5-second timeout (context deadline exceeded). To prevent timeouts, webhook_server.py sends HTTP 200 OK back to Gitea in less than 1 millisecond, then detaches deploy.sh into an independent background process using subprocess.Popen(..., close_fds=True).
• Files:
  • Script: /var/www/freshers-hub/webhook_server.py
  • Systemd Service: /etc/systemd/system/webhook.service

---

Component 4: Deployment Execution Engine (deploy.sh)

• Role: Shell script that performs the actual pulling, building, packaging, and service restarts.
• File Location: /var/www/freshers-hub/deploy.sh
• Execution Steps inside deploy.sh:

#!/bin/bash
export PATH=$PATH:/usr/local/bin:/usr/bin:/bin:/usr/local/go/bin:/root/.nvm/versions/node/$(ls /root/.nvm/versions/node 2>/dev/null | tail -n 1)/bin
export NVM_DIR="/root/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

echo "==========================================" >> /var/log/deploy.log
echo "🚀 Deploying latest code at $(date)" >> /var/log/deploy.log

cd /var/www/freshers-hub

# Step 1: Force hard reset to match Gitea 100%
git fetch origin main >> /var/log/deploy.log 2>&1
git reset --hard origin/main >> /var/log/deploy.log 2>&1

# Step 2: Build React PWA Frontend
npm install >> /var/log/deploy.log 2>&1
npm run build >> /var/log/deploy.log 2>&1

# Step 3: Build Go AI Chatbot Engine
(cd chatbot-service && go build -o chatbot-service main.go) >> /var/log/deploy.log 2>&1

# Step 4: Build Spring Boot Java Backend JAR
chmod +x backend/mvnw
(cd backend && ./mvnw clean package -DskipTests) >> /var/log/deploy.log 2>&1

# Step 5: Check Python Dependencies for Telegram Bot
if [ -f "telegram-bot/requirements.txt" ]; then
    (cd telegram-bot && ./venv/bin/pip install -r requirements.txt) >> /var/log/deploy.log 2>&1
fi

# Step 6: Restart All Linux Systemd Microservices
systemctl restart springboot chatbot telegram-bot nginx >> /var/log/deploy.log 2>&1

echo "✅ Deployment completed successfully at $(date)" >> /var/log/deploy.log

---

Component 5: Production Microservices & Infrastructure

The pipeline automatically manages 5 production subsystems on your VPS:

Subsystem	Service Name	Role	Port / Target
Nginx Web Server	nginx.service	Serves compiled React PWA static assets & acts as Reverse Proxy	Port 80 / 443 ➔ /var/www/freshers-hub/dist
Spring Boot Java Backend	springboot.service	Core REST API (Database, Bus Location Tracking, LeetCode Sync)	Port 8085
Go Chatbot Engine	chatbot.service	Instant Q&A Vector Search & RAG Chatbot Engine	Port 8081
Python Telegram Bot	telegram-bot.service	24/7 Telegram & Discord Developer Collaboration Bot	Background Poll Daemon
Webhook Listener	webhook.service	Receives Gitea push triggers and executes deployments	Port 9000

---

📁 3. Server Directory Tree Summary

/var/www/freshers-hub/                    <-- Project Root Directory
├── deploy.sh                             <-- Deployment execution script
├── webhook_server.py                     <-- HTTP listener on port 9000
│
├── dist/                                 <-- Compiled static frontend assets (Nginx root)
│   ├── index.html
│   └── assets/ (index-*.js, index-*.css)
│
├── backend/                              <-- Spring Boot Java Backend
│   ├── mvnw                              <-- Executable Maven wrapper (chmod +x)
│   └── target/freshers-hub-0.0.1.jar     <-- Compiled Java JAR artifact
│
├── chatbot-service/                      <-- Go AI Engine
│   └── chatbot-service                   <-- Compiled Go binary executable
│
└── telegram-bot/                         <-- Python Telegram Bot
    ├── telegram_bot.py
    └── venv/                             <-- Virtualenv with Python packages

/var/log/
└── deploy.log                            <-- Real-time timestamped build logs

---

🛠️ 4. Operational Commands & Maintenance

How to View Real-Time Build Logs:

Run on VPS (ssh root@129.121.126.66):

tail -f /var/log/deploy.log

How to Check Webhook Listener Status:

systemctl status webhook

How to Restart Webhook Listener manually:

systemctl restart webhook

How to Manually Trigger Deployment:

/var/www/freshers-hub/deploy.sh

---

🛡️ 5. Key Resilience Safeguards Implemented

1. git reset --hard origin/main: Ensures the server never gets stuck on diverged branches or uncommitted temporary files.
2. close_fds=True in Python Popen: Detaches process execution so Gitea gets an HTTP 200 response in <1ms, avoiding timeout errors.
3. Automatic Dependency Sync (npm install & pip install): Guarantees that adding new libraries to package.json or requirements.txt won't break server builds.
4. Explicit chmod +x on Maven Wrapper (backend/mvnw): Prevents permission errors during Java JAR compilation.