Skip to content

COMPREHENSIVE_SETUP_GUIDE.md

Latest commit

 

History

History
153 lines (118 loc) · 4.2 KB

COMPREHENSIVE_SETUP_GUIDE.md

File metadata and controls

153 lines (118 loc) · 4.2 KB

🚀 Gratech Comet-X - Complete Setup Guide

Date: 2025-12-13
Owner: Grar00t
Project: gratech-comet-x

📋 Overview

This is the complete setup guide for the Gratech Comet-X project, including:

  • ✅ Three-Lobe Brain Architecture (Executive/Sensory/Cognitive)
  • ✅ GitHub Actions Workflows (CodeQL, Azure OIDC, Docker GHCR, Trivy)
  • ✅ Dependabot configuration with groups
  • ✅ Security policies (SECURITY.md)
  • ✅ Issue/PR templates
  • ✅ Branch protection rules
  • ✅ OIDC setup with Azure Entra ID

🎯 Quick Start Commands

# 1. Extract project files
cd ~/gratech-comet-x-final
unzip ~/clearpath/GrAtech-Assistant-Starter-v2.0.0.zip -d .

# 2. Initialize Git
git init -b main
git add .
git commit -m "Initial: Comet-X Full Setup"

# 3. Create GitHub repository
gh repo create Grar00t/gratech-comet-x --private --source=. --push

# 4. Add secrets (names only - enter values manually)
gh secret set X_API_KEY
gh secret set X_API_SECRET
gh secret set X_ACCESS_TOKEN
gh secret set X_ACCESS_SECRET
gh secret set X_BEARER_TOKEN
gh secret set X_CLIENT_ID
gh secret set X_CLIENT_SECRET
gh secret set AZURE_TENANT_ID
gh secret set AZURE_SUBSCRIPTION_ID
gh secret set AZURE_CLIENT_ID

# 5. Enable branch protection
gh api -X PUT repos/Grar00t/gratech-comet-x/branches/main/protection \
  -H "Accept: application/vnd.github+json" \
  -F required_pull_request_reviews='{"required_approving_review_count":1}' \
  -F enforce_admins=true \
  -F required_status_checks='{"strict":true,"contexts":["CodeQL Analysis","Security Scan (Trivy)","CI-CD (CometX) - Azure OIDC"]}'

🔐 Azure OIDC Setup

Step 1: Create App Registration in Entra ID

# In Azure Portal:
# 1. Microsoft Entra ID → App registrations → New registration
# 2. Name: gratech-cometx-ci
# 3. Type: Single tenant
# 4. Copy: Application (client) ID and Directory (tenant) ID

Step 2: Add Federated Credential

Issuer: https://token.actions.githubusercontent.com
Subject: repo:Grar00t/gratech-comet-x:ref:refs/heads/main
Audience: api://AzureADTokenExchange

Step 3: Grant IAM Roles

# In Azure Portal:
# Subscriptions → Access control (IAM) → Add role assignment
# Role: Contributor (or custom)
# Assign to: gratech-cometx-ci service principal

📦 Project Structure

gratech-comet-x/
├── .github/
│   ├── workflows/
│   │   ├── codeql-analysis.yml
│   │   ├── deploy.yml
│   │   ├── security-trivy-sarif.yml
│   │   └── docker-publish-ghcr.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── dependabot.yml
├── README.md
├── SECURITY.md
└── PULL_REQUEST_TEMPLATE.md

🎨 Three-Lobe Architecture

flowchart TD
    subgraph "Comet-X Digital Entity"
        Executive[Executive Lobe<br/>Service Worker<br/>Hydration/Dehydration]
        Sensory[Sensory Lobe<br/>Shadow DOM<br/>X Feed Reading]
        Cognitive[Cognitive Lobe<br/>Offscreen Canvas<br/>Local Models]
        
        User[X User] -->|Input| Sensory
        Sensory -->|Context| Executive
        Executive -->|Coordination| Cognitive
        Cognitive -->|Response| Executive
        Executive -->|Output| User
    end
Loading

✅ Verification Checklist

  • Repository created: Grar00t/gratech-comet-x
  • All secrets added in GitHub
  • OIDC configured in Azure Entra ID
  • Branch protection enabled on main
  • CodeQL workflow running
  • Trivy scan uploading SARIF
  • Dependabot opening PRs
  • Health check passing: curl https://api.gratech.sa/health

📚 References

Next Steps: Follow the Quick Start Commands above to deploy everything!