CI/CD Auto-Deployer Engine

The Auto-Deployer Service (vps-deployer) is a custom lightweight Python HTTP daemon running inside Docker. It listens for incoming GitHub push event webhooks and automatically triggers code pulls and container rebuilds on the VPS.

🏗️ Architecture & Security Model

sequenceDiagram
    autonumber
    participant GitHub as "🐙 GitHub Action / Push"
    participant Nginx as 🛡️ Nginx Reverse Proxy
    participant Deployer as "⚡ vps-deployer (:9000)"
    participant Git as "📂 /opt/vps-apps/..."
    participant Docker as 🐳 Docker Socket
    participant GChat as 💬 Google Chat Channel

    GitHub->>Nginx: POST /deploy-webhook (Headers: X-Hub-Signature-256)
    Nginx->>Deployer: Proxy to http://vps-deployer:9000/
    Deployer->>Deployer: Compute HMAC-SHA256(Payload, WEBHOOK_SECRET)
    alt Signature Mismatch
        Deployer-->>GitHub: HTTP 403 Forbidden
    else Signature Valid
        Deployer-->>GitHub: HTTP 200 Deployment Accepted
        Deployer->>Git: git checkout {branch} && git pull --ff-only
        opt Post-deploy tasks
            Deployer->>Docker: Execute docker restart / build
        end
        Deployer->>GChat: Send success/failure notification card
    end

1. Cryptographic Signature Verification

GitHub sends the X-Hub-Signature-256 header containing sha256=<hex-digest>. The deployer compares this against an HMAC-SHA256 signature calculated from the raw payload bytes and WEBHOOK_SECRET using hmac.compare_digest() to prevent timing attacks.

2. Privileged Docker Socket Integration

The vps-deployer container mounts the host Docker socket (/var/run/docker.sock) and application directories (/opt/vps-apps, /opt/vps-stack). This gives the Python process permission to restart containers and trigger rebuilds without requiring SSH access.

🗺️ Repository & Branch Mapping (`deployer.py`)

The service orchestrates 5 production repositories across main, develop, and dev branches:

Repository Name	Monitored Branches	Target Directory on VPS	Environment	Post-Deploy Trigger
`planovi-webpage`	`main`, `develop`, `dev`	`/opt/vps-apps/webpage/[prod\|dev]`	PROD / DEVELOP	None (Static files served directly)
`planovi-microservices`	`main`, `develop`, `dev`	`/opt/vps-apps/microservices/[prod\|dev]`	PROD / DEVELOP	Permissions sync (`chmod -R 775 data/`)
`planovi-flutter-app`	`main`, `develop`, `dev`	`/opt/vps-apps/flutter-app/[prod\|dev]`	PROD / DEVELOP	`flutter_build` (Flutter Web compilation & Nginx reload)
`planovi-converter`	`main`, `develop`, `dev`	`/opt/vps-apps/converters/[prod\|dev]`	PROD / DEVELOP	`converter_build` (`docker compose build converters-api-*`)
`planovi-backend`	`main`, `develop`, `dev`	`/opt/vps-apps/backend/[prod\|dev]`	PROD / DEVELOP	`supabase_functions_sync` (Copies functions & restarts Edge Runtime)

🔔 Google Chat Incident & Deploy Notifications

When GOOGLE_CHAT_WEBHOOK_URL is set, deployer.py sends formatted cards into the engineering room:

{
  "cards": [{
    "header": {
      "title": "🚀 Planovi Deployer: SUCCESS",
      "subtitle": "Repository: planovi-backend [PROD]"
    },
    "sections": [{
      "widgets": [{
        "textParagraph": {
          "text": "<b>Commit:</b> <code>7bca88d</code> by Mateusz<br><b>Message:</b> Update telemetry parsing<br><b>Status:</b> Edge Functions synchronized."
        }
      }]
    }]
  }]
}

If an error occurs during git pull or container restart, an alert card with the error trace is immediately pushed to the channel.

🛠️ Inspecting Deployer Logs

# Watch real-time webhook executions and deployment output
docker logs -f vps-deployer

# Trigger a test ping to the webhook endpoint
curl -X POST http://127.0.0.1:9000/ -H "Content-Type: application/json" -d '{"ping": true}'