Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
261 lines (195 loc) · 6.99 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

261 lines (195 loc) · 6.99 KB
Raw

🚀 Gratech Comet-X - Quick Deployment Guide

📋 Project Overview

Repository: Grar00t/gratech-comet-x
Purpose: Browser-Native Local-First AI Platform with Three-Lobe Architecture
Deployment Options: GitHub Pages, Azure Static Web, Azure Front Door + CDN

🎯 Available Deployment Methods

1. GitHub Pages (Automatic)

Setup Steps:

  1. Go to repository Settings → Pages
  2. Source: GitHub Actions
  3. Push to main branch triggers deployment automatically

2. Azure Static Web (OIDC)

  • URL: https://<storage-account>.z13.web.core.windows.net/
  • Workflow: .github/workflows/azure-static-web.yml
  • Source: docs/public/ directory
  • Status: Azure Static Web

Required GitHub Secrets:

gh secret set AZURE_CLIENT_ID
gh secret set AZURE_TENANT_ID
gh secret set AZURE_SUBSCRIPTION_ID

Optional GitHub Variables (with defaults):

gh variable set AZURE_RESOURCE_GROUP -b "rg-gratech-comet"
gh variable set AZURE_STORAGE_ACCOUNT -b "stgratechcometweb"
gh variable set AZURE_LOCATION -b "eastus"

Azure OIDC Setup:

See docs/SETUP_GUIDE.md

3. Azure Front Door + CDN (Optional)

  • Purpose: Global CDN, WAF, Custom Domain, SSL Certificates
  • Setup Guide: docs/AZURE_FRONTDOOR_SETUP.md
  • Custom Domain: ai.gratech.sa or www.gratech.sa

Key Features:

  • ✅ Global content delivery
  • ✅ Web Application Firewall (WAF)
  • ✅ Managed SSL certificates
  • ✅ Custom domain support
  • ✅ DDoS protection
  • ✅ Automatic HTTPS redirect

🔒 Security Setup

Branch Protection

Run the automated script:

./scripts/setup-branch-protection.sh

Or configure manually at:
https://github.com/Grar00t/gratech-comet-x/settings/branches

Protection Rules:

  • Require pull request reviews (1 approval)
  • Require status checks to pass:
    • CodeQL
    • CI-CD (CometX) - Azure OIDC
    • Security Scan (Trivy)
    • GitHub Pages deployment
    • Azure Static Web deployment
  • Enforce for administrators
  • Block force pushes
  • Block branch deletion

📦 CI/CD Workflows

Active Workflows:

  1. CodeQL Analysis (.github/workflows/codeql-analysis.yml)

    • Security scanning for JavaScript/TypeScript
    • Runs on: push, PR, weekly schedule
    • Results: Security → Code scanning alerts

  2. CI-CD Azure OIDC (.github/workflows/deploy.yml)

  3. Docker → GHCR (.github/workflows/docker-publish-ghcr.yml)

    • Builds and publishes to GitHub Container Registry
    • Image: ghcr.io/grar00t/gratech-comet-x:latest

  4. Security Scan - Trivy (.github/workflows/security-trivy-sarif.yml)

    • Scans filesystem and Docker images
    • Uploads SARIF to Security tab
    • Fails on CRITICAL vulnerabilities

  5. GitHub Pages (.github/workflows/pages.yml)

    • Deploys landing page to GitHub Pages
    • Source: docs/public/

  6. Azure Static Web (.github/workflows/azure-static-web.yml)

    • OIDC-based deployment to Azure Storage
    • Automatic $web container management
    • Preview deployments on PRs

🎨 Landing Page

The landing page (docs/public/index.html) features:

  • RTL Arabic design
  • Responsive layout
  • Three-Lobe Architecture visualization
  • Feature highlights
  • Status badges
  • Direct links to documentation

Preview:

After deployment, visit:

🚦 Quick Start Commands

1. First-Time Setup

# Clone repository
git clone https://github.com/Grar00t/gratech-comet-x.git
cd gratech-comet-x

# Configure Azure OIDC (one-time)
# Follow: docs/SETUP_GUIDE.md

# Add GitHub secrets
gh secret set AZURE_CLIENT_ID -b "YOUR_CLIENT_ID"
gh secret set AZURE_TENANT_ID -b "YOUR_TENANT_ID"
gh secret set AZURE_SUBSCRIPTION_ID -b "YOUR_SUBSCRIPTION_ID"

# Setup branch protection
./scripts/setup-branch-protection.sh

2. Deploy

# Push to main triggers all workflows
git push origin main

# Monitor workflows
gh run watch

# Check deployments
gh run list --workflow=pages.yml
gh run list --workflow=azure-static-web.yml

3. Verify Deployments

# GitHub Pages
curl -I https://grar00t.github.io/gratech-comet-x/

# Azure Static Web (get URL from workflow output)
gh run view --workflow=azure-static-web.yml

# Check all workflows status
gh run list

📊 Monitoring & Verification

GitHub Actions

Security Tab

GitHub Pages Settings

🆘 Troubleshooting

GitHub Pages 404 Error

# Verify Pages is enabled
gh api repos/Grar00t/gratech-comet-x/pages

# Check workflow logs
gh run view --workflow=pages.yml --log

Azure OIDC Login Fails

# Verify secrets are set
gh secret list

# Verify federated credential in Azure
az ad app federated-credential list --id <APP_ID>

# Check subject matches exactly:
# repo:Grar00t/gratech-comet-x:ref:refs/heads/main

Workflow Not Triggering

# Verify workflows are enabled
gh api repos/Grar00t/gratech-comet-x/actions/workflows

# Check branch protection isn't blocking
gh api repos/Grar00t/gratech-comet-x/branches/main/protection

📚 Additional Resources

🎯 Status Badges

CI-CD Azure OIDC CodeQL Docker GHCR Security Scan GitHub Pages Azure Static Web

Last Updated: 2025-12-13
Maintainer: Grar00t
License: MIT