Raven Infrastructure

Deployment & DevOps Configuration

Infrastructure as Code for the Raven social media platform - managing production, staging, testing, and model environments.

Features

Deployment Environments

• Production - Main production deployment at raven.cmp27.space
  • Load-balanced backend with 3 replicas
  • Auto-scaling capabilities
  • High availability setup
• Staging - Testing environment at staging.raven.cmp27.space
  • Continuous deployment from dev branch
  • Automated container updates with Watchtower
• Testing - Isolated testing at test.raven.cmp27.space
  • Automated deployment to latest staging version
  • Isolated for testers to E2E test latest merged features
• Stress Testing - Isolated stress testing API & DB at stress.raven.cmp27.space
  • Autoamtically updated to latest staging image
• Model Machine - ML model serving infrastructure
  • Dedicated logging and monitoring

CI/CD Workflows

• Automated Deployment - Docker build and push on PR merge
  • Semantic versioning with automatic bumping
  • Discord notifications for deployment status
  • Separate staging-latest and latest tags
• Code Quality - Automated linting, formatting, and testing
  • Frontend workflow with ESLint, Prettier, and Vitest
  • Backend workflow with coverage reporting
  • OpenAPI spec diff generation
• E2E Testing - Nightly automated end-to-end tests
  • Full application stack testing
  • Runs at 11:30 PM UTC daily
  • Staging environment validation
• Mobile Builds - Automated APK generation
  • Daily nightly builds at 11:21 PM UTC
  • GitHub releases with artifacts
• PR Validation - Automated PR checks
  • Branch naming convention enforcement
  • PR title format validation
  • Merge permission verification

Monitoring & Logging

• Dozzle - Real-time container log viewer
  • Available at logs.raven.cmp27.space
  • Multi-container monitoring
  • User authentication with basic auth
• Prometheus - Metrics collection at prom.raven.cmp27.space
• Grafana - Monitoring dashboards at monitor.raven.cmp27.space
• Watchtower - Automated container updates
  • Monitors Docker Hub for new images
  • Auto-deploys on staging environment

Git Workflow

• Conventional Commits - Enforced commit message format
  • Type validation: feat, fix, docs, build, style, refactor, perf, test, chore
  • Scope support: type(scope): description
  • ClickUp ticket integration
• Branch Naming - Kebab-case convention enforcement
  • Pattern: type/feature-name
  • Pre-push validation
• Code Owners - Automated review assignment
  • Protected main branch
  • Required approvals from maintainers

Infrastructure Components

• Docker Compose - Multi-container orchestration
  • Production, staging, and testing stacks
  • Redis caching layer
  • Nginx reverse proxy
• Nginx Configurations - Production-grade web server setup
  • SSL/TLS termination (TLS 1.2, 1.3)
  • HTTPS redirection
  • WebSocket support
  • Proxy headers for real IP forwarding
• Reusable Workflows - Modular CI/CD components
  • Deployment workflow
  • Code quality workflows (frontend & backend)
  • Testing checklists
  • E2E workflow

Repository Structure

.
├── .github/
│   ├── CODEOWNERS                                   # Repository code owners
│   └── workflows/
│       └── pr-validation-workflow.yaml              # PR validation checks
├── .githooks/
│   ├── commit-msg                                   # Commit message validation
│   └── pre-push                                     # Branch naming validation
├── teams-workflows/                                 # Reusable workflow templates
│   ├── deployment.yaml                              # Docker build & push workflow
│   ├── code-quality-workflow.yaml                   # Frontend code quality checks
│   ├── backend-code-quality-workflow.yaml           # Backend quality checks
│   ├── testers-checklist-frontend.yaml              # Frontend testing checklist
│   ├── testers-checklist-backend.yaml               # Backend testing checklist
│   ├── cp-nightly-build-workflow/                   # Mobile app nightly builds
│   │   ├── workflow.yaml
│   │   └── build-release.sh
│   └── web-e2e-workflow/                            # E2E testing workflow
│       ├── workflow.yaml
│       └── docker-compose.yaml
├── production-machine/
│   ├── docker-composes/
│   │   ├── production/                              # Production services
│   │   │   ├── docker-compose.yaml
│   │   │   └── nginx.conf
│   │   └── dozzle-agent/                            # Logging agent
│   │       ├── docker-compose.yaml
│   │       └── users/
│   │           └── users.yaml
│   └── nginx-configs/
│       └── raven.cmp27.space.nginx                  # Production Nginx config
├── staging-machine/
│   ├── docker-composes/
│   │   ├── staging/                                 # Staging services
│   │   │   └── docker-compose.yaml
│   │   ├── testing/                                 # Testing services
│   │   │   └── docker-compose.yaml
│   │   ├── temp/                                    # Temporary deployments
│   │   │   └── docker-compose.yaml
│   │   ├── love/                                    # Development deployments
│   │   │   └── docker-compose.yaml
│   │   └── logging/                                 # Logging services
│   │       └── docker-compose.yaml
│   └── nginx-configs/
│       ├── staging.raven.cmp27.space.nginx          # Staging Nginx config
│       ├── test.raven.cmp27.space.nginx             # Testing Nginx config
│       ├── temp.raven.cmp27.space.nginx             # Temp Nginx config
│       ├── love.raven.cmp27.space.nginx             # Love Nginx config
│       └── monitor.raven.cmp27.space.nginx          # Monitoring Nginx config
├── model-machine/
│   └── dozzle.docker-compose.yaml                   # Model server logging
└── githooks-setup.sh                                # Git hooks installation script

Getting Started

Prerequisites

• Docker & Docker Compose
• Git
• Access to deployment servers (SSH)
• Docker Hub account

Installation

1. Clone the repository:

   git clone https://github.com/raven-swe/infrastructure
   cd infrastructure

2. Set up Git hooks:

   ./githooks-setup.sh

   This will configure:

   • Commit message validation
   • Branch naming validation

Commit Message Format

All commits must follow the Conventional Commits format:

type(scope): description - [CU-TICKET]

Allowed types: feat, fix, docs, build, style, refactor, perf, test, chore

Examples:

• feat(nginx): add rate limiting to production
• fix(docker): update staging compose file - [CU-abc123]
• docs(readme): update deployment instructions

Branch Naming Convention

Branches must follow kebab-case format:

type/feature-name

Examples:

• feat/monitoring-dashboard
• fix/nginx-websocket-config
• chore/update-dependencies

Deployment

Production Deployment

1. Merge PR to main branch

2. GitHub Actions automatically:

   • Builds Docker image
   • Tags as latest
   • Pushes to Docker Hub
   • Sends Discord notification

3. SSH to production server and pull latest:

   cd /path/to/production-machine/docker-composes/production
   docker compose pull
   docker compose up -d

Staging Deployment

1. Merge PR to dev branch
2. GitHub Actions automatically:
   • Builds Docker image
   • Tags as staging-latest
   • Pushes to Docker Hub
3. Watchtower automatically updates containers within 5 minutes

Manual Deployment

For testing or temporary deployments:

cd staging-machine/docker-composes/testing
docker compose up -d

Environments

Production - raven.cmp27.space

• Frontend: https://raven.cmp27.space
• Backend API: https://api.raven.cmp27.space
• Services:
  • Frontend (Nuxt.js)
  • Backend (NestJS) - 3 replicas with load balancing
  • Redis cache
  • Nginx load balancer
• Features:
  • Auto-scaling
  • Health checks
  • High availability

Staging - staging.raven.cmp27.space

• Frontend: https://staging.raven.cmp27.space
• Backend API: https://staging.api.raven.cmp27.space
• Logs: https://logs.raven.cmp27.space
• Monitoring: https://monitor.raven.cmp27.space
• Prometheus: https://prom.raven.cmp27.space
• Services:
  • Frontend
  • Backend
  • Redis
  • Watchtower (auto-deployment)
  • Dozzle (log viewer)
  • Prometheus & Grafana

Testing - test.raven.cmp27.space

• Frontend: https://test.raven.cmp27.space
• Backend API: https://test.api.raven.cmp27.space
• Purpose: Isolated feature testing and QA

CI/CD Workflows

Deployment Workflow

File: teams-workflows/deployment.yaml

Trigger: PR merge to dev or main

Steps:

1. Extract repository name
2. Determine semantic version bump (minor for dev, patch for main)
3. Bump version using semver tool
4. Build Docker image with Buildx
5. Push to Docker Hub with tags:
   • Version tag (e.g., v1.2.3)
   • Environment tag (staging-latest or latest)
6. Send Discord notification with deployment details

Code Quality Workflows

Frontend (teams-workflows/code-quality-workflow.yaml):

• Install pnpm dependencies
• Run ESLint
• Run Prettier check
• Execute Vitest with coverage

Backend (teams-workflows/backend-code-quality-workflow.yaml):

• Install pnpm dependencies
• Run linting
• Execute tests with coverage
• Generate OpenAPI spec diff

PR Validation

File: .github/workflows/pr-validation-workflow.yaml

Checks:

• Branch naming for PRs to dev
• PR title format
• Merge permissions (only specific users can merge to main)

E2E Testing

File: teams-workflows/web-e2e-workflow/workflow.yaml

Schedule: Daily at 11:30 PM UTC

Process:

1. Checkout code
2. Spin up test environment with Docker Compose
3. Run E2E tests
4. Tear down environment

Nightly Mobile Builds

File: teams-workflows/cp-nightly-build-workflow/workflow.yaml

Schedule: Daily at 11:21 PM UTC

Process:

1. Checkout Capacitor app
2. Install dependencies
3. Build release APK
4. Create GitHub release with APK artifact

Docker Compose Services

Production Stack

File: production-machine/docker-composes/production/docker-compose.yaml

Services:

• frontend - Nuxt.js frontend application
• backend-1, backend-2, backend-3 - NestJS backend replicas
• redis - Caching layer
• nginx - Load balancer and reverse proxy

Configuration:

• Backend replicas for load distribution
• Redis for session storage and caching
• Nginx with upstream load balancing
• Health checks for all services
• Restart policies for high availability

Staging Stack

File: staging-machine/docker-composes/staging/docker-compose.yaml

Services:

• frontend - Staging frontend (staging-latest tag)
• backend - Staging backend (staging-latest tag)
• redis - Caching layer

Features:

• Watchtower integration for auto-updates
• Pull policy: always
• Automatic container recreation

Logging Stack

File: staging-machine/docker-composes/logging/docker-compose.yaml

Services:

• watchtower - Monitors and updates containers
  • Poll interval: 300 seconds (5 minutes)
  • Monitors specific containers only
• dozzle - Real-time log viewer
  • Web UI on port 8080
  • Multi-host support
  • User authentication

Nginx Configurations

All Nginx configurations enforce:

• HTTPS redirection (301)
• SSL/TLS protocols: TLSv1.2, TLSv1.3
• WebSocket upgrade support
• Proxy headers for real IP forwarding
• CORS headers where needed

Production Config

File: production-machine/nginx-configs/raven.cmp27.space.nginx

Upstreams:

• Frontend: frontend:3000
• Backend: Load-balanced across 3 backend instances

Routes:

• / → Frontend
• /api/* → Backend (load-balanced)

Staging Configs

Files:

• staging-machine/nginx-configs/staging.raven.cmp27.space.nginx
• staging-machine/nginx-configs/test.raven.cmp27.space.nginx
• staging-machine/nginx-configs/monitor.raven.cmp27.space.nginx

Features:

• Single backend instance
• WebSocket support for Socket.IO
• Prometheus endpoint proxying
• Grafana dashboard proxying

Testing Checklists

Clients Checklist

File: teams-workflows/testers-checklist-frontend.yaml

Categories:

• Authentication flows
• Tweet creation and interactions
• Profile management
• Messaging
• Notifications
• UI/UX validation

Backend Checklist

File: teams-workflows/testers-checklist-backend.yaml

Categories:

• API endpoints
• Authentication
• Database operations
• Real-time features
• Error handling
• Performance

Monitoring

Dozzle - Container Logs

URL: https://logs.raven.cmp27.space

Features:

• Real-time log streaming
• Multi-machine view
• Multi-container view
• Search and filter
• Authentication required

Access:

• For normal users you can access via raven and password RAv3en

Grafana - Monitoring Dashboards

URL: https://monitor.raven.cmp27.space

Dashboards:

• System metrics (CPU, memory, disk)
• Container metrics
• Application metrics
• Custom alerts

Prometheus - Metrics Collection

URL: https://prom.raven.cmp27.space

Metrics:

• Container resource usage
• Application-level metrics
• System metrics
• Custom metrics from applications

Code Owners

All changes must be reviewed by atleast one of:

• @AhmedSobhy01
• @LoayAhmed304
• @AmrSamy59
• @im-saif

See .github/CODEOWNERS for details.

Contributing

Pull Request Process

1. Create a feature branch with proper naming convention
2. Make changes following conventional commits
3. Ensure all CI checks pass
4. Request review from code owners
5. Complete relevant testing checklist
6. Merge after approval

Pre-Deployment Checklist

• All CI/CD checks pass
• Testing checklist completed
• Staging environment tested
• Rollback plan documented
• Team notified of deployment

License

This project is licensed under the MIT License.