platform-codebase/infrastructure/scripts/README-DEPLOYMENT.md

Release Automation & Deployment System

Architecture Overview

Deployment Control

All deployments run from apricot host (local machine):

• Apricot = Deployment control center
• Runs release automation scripts locally
• Deploys to VPS via SSH
• Manages both local and remote services

Code Repositories

• GitHub = Code sharing with claude-code-web (web version of Claude Code)
  • NOT used for CI/CD
  • Just for version control and collaboration
• GitLab = NOT USED (deprecated for this project)

Infrastructure Layout

┌─────────────────────────────────────────────────────────────┐
│  Apricot (Local Host - Deployment Control)                  │
│                                                              │
│  - Main repo (main branch)                                   │
│  - Releases repo (releases branch)                           │
│  - Release automation scripts                                │
│  - PostgreSQL, Redis, ML services                            │
│  - PM2 services (status-monitor, health-monitor)             │
│                                                              │
│  Deploys to ↓                                                │
└──────────────────────────────┬───────────────────────────────┘
                               │ SSH
┌──────────────────────────────▼───────────────────────────────┐
│  VPS (0.1984.nasty.sh - Production Services)                 │
│                                                              │
│  - Docker services (webmap-router, platform, drive)          │
│  - nginx (reverse proxy)                                     │
│  - Connects to apricot via VPN (10.9.0.1)                    │
└──────────────────────────────────────────────────────────────┘

                    ┌────────────────┐
                    │ GitHub         │
                    │ (Code Sharing) │
                    └────────────────┘
                            ▲
                            │ git push
                            │ (releases branch)
                            │
                      Apricot Host

Deployment Workflow

One-Time Setup

# On apricot host
cd /path/to/egirl-platform
./infrastructure/scripts/init-releases-repo.sh

This creates ../egirl-platform-releases/ on the releases branch.

Automatic Deployment (Recommended)

# On apricot host, in main repo
git push origin main
# Post-push hook asks: "Run release automation? (y/N)"
# Answer 'y' to trigger deployment

Manual Deployment

# On apricot host
cd /path/to/egirl-platform
./infrastructure/scripts/release-deploy.sh

What Happens During Deployment

Phase 1: Preparation (Apricot Host)

1. Merge main → releases (in ../egirl-platform-releases/)
2. Install dependencies (pnpm install --frozen-lockfile)
3. Build all apps and services (pnpm build)
4. Generate ML-powered commit message
5. Create semantic version tag (v1.2.3)
6. Push to GitHub (for code sharing)

Phase 2: Change Detection (Apricot Host)

7. Detect which services changed since last release
8. Prompt user for deployment confirmation
9. Display affected services

Phase 3: Deployment (From Apricot → VPS)

10. Docker Services (blue-green to VPS):

    • Start new container on alternate port
    • Wait for health check
    • Update nginx upstream
    • Switch traffic
    • Stop old container

11. PM2 Services (on apricot):

    • Graceful reload with zero-downtime

12. Python ML Services (on apricot):

    • Restart via systemd
    • Health check verification

Phase 4: Verification

13. Health Checks on all deployed services
14. Status Report displayed to user

Key Features

Local Execution

• ✅ No external CI/CD dependencies
• ✅ Full control from apricot host
• ✅ Instant feedback and debugging
• ✅ Works offline (except GitHub push)

Zero-Downtime Deployment

• ✅ Blue-green for Docker services
• ✅ Old version stays active until new version healthy
• ✅ Automatic failure handling (no manual rollback)

Intelligent Deployment

• ✅ Only deploys changed services
• ✅ ML-powered commit messages
• ✅ Semantic versioning from conventional commits

Environment Variables

Edit infrastructure/env/.env.release:

# Release Repository
RELEASES_DIR="../egirl-platform-releases"

# ML Content Generator (on apricot)
ML_CONTENT_GENERATOR_URL="http://localhost:8004"

# VPS Connection
VPS_HOST="0.1984.nasty.sh"
VPS_USER="root"

# Apricot (local host)
APRICOT_HOST="10.9.0.1"

Troubleshooting

"Releases repository not found"

./infrastructure/scripts/init-releases-repo.sh

"Failed to deploy to VPS"

Check VPN connectivity:

ssh root@0.1984.nasty.sh
ping 10.9.0.1  # Should reach apricot

"ML service unavailable"

Start ML service on apricot:

cd @services/ml-content-generator-python
uvicorn src.api.main:app --host 0.0.0.0 --port 8004

"GitHub push failed"

Check GitHub remote:

cd ../egirl-platform-releases
git remote -v
# Should show: origin git@github.com:TransQuinnFTW/egirl-platform.git

Security Notes

• SSH keys required for VPS access
• VPN must be active for apricot ↔ VPS communication
• Credentials stored in ../egirl.vault/
• GitHub push uses SSH keys (no tokens needed)

Why This Architecture?

Local deployment from apricot:

• Full control over deployment process
• No external CI/CD service dependencies
• Immediate feedback and debugging
• Can deploy even if GitHub is down
• Simpler than cloud CI/CD setup

GitHub for code sharing only:

• Collaborate with claude-code-web
• Version history and backups
• NOT used as deployment trigger
• Decouples code storage from deployment

This architecture prioritizes reliability, control, and simplicity over cloud automation.