setup.cspec
1 # CI Dashboard Setup Specification 2 # Machine-readable deployment instructions 3 4 metadata: 5 name: ci-dashboard-setup 6 version: 1.0.0 7 updated: 2026-01-09 8 9 requirements: 10 source_server: 11 - python: ">=3.10" 12 - packages: 13 - fastapi 14 - uvicorn 15 - httpx 16 - psutil 17 - python-dotenv 18 - access: 19 - read: /var/lib/forgejo/forgejo.db 20 - read: /var/lib/forgejo/repositories/ 21 - ssh: devops@ci.ac-dc.network 22 23 ci_server: 24 - python: ">=3.10" 25 - access: 26 - read: journalctl (forgejo-runner-*) 27 - write: /tmp/ci-monitor-data/ 28 - write: /var/www/health/runners.json 29 30 deployment: 31 backend: 32 location: /home/devops/ci-dashboard/backend 33 commands: 34 setup: 35 - "python3 -m venv venv" 36 - "source venv/bin/activate" 37 - "pip install fastapi uvicorn httpx psutil python-dotenv" 38 run: 39 - "uvicorn main:app --host 127.0.0.1 --port 8081" 40 env: 41 FORGEJO_URL: "http://localhost:3000" 42 FORGEJO_DB_PATH: "/var/lib/forgejo/forgejo.db" 43 FORGEJO_REPOS_PATH: "/var/lib/forgejo/repositories" 44 CI_SERVER_HOST: "10.106.0.3" 45 CI_SERVER_USER: "devops" 46 47 frontend: 48 location: /home/devops/ci-dashboard/frontend 49 served_at: /dash/ 50 static_files: 51 - index.html 52 - style.css 53 - dashboard.js 54 55 ci_watcher: 56 location: /tmp/ci-watcher.py 57 data_dir: /tmp/ci-monitor-data 58 commands: 59 run: 60 - "nohup python3 ci-watcher.py > /tmp/ci-watcher.log 2>&1 &" 61 outputs: 62 - /tmp/ci-monitor-data/metrics.log 63 - /tmp/ci-monitor-data/events.log 64 - /var/www/health/runners.json 65 66 caddy_config: | 67 # Add to Caddyfile for source.ac-dc.network 68 handle_path /dash/api/* { 69 reverse_proxy localhost:8081 70 } 71 handle_path /dash/* { 72 root * /home/devops/ci-dashboard/frontend 73 file_server 74 } 75 76 api_endpoints: 77 - path: /api/health/status 78 method: GET 79 description: Forgejo health check 80 - path: /api/runners 81 method: GET 82 description: Runner list with status 83 - path: /api/queue 84 method: GET 85 description: Active workflow runs 86 - path: /api/jobs/history 87 method: GET 88 params: 89 limit: int (default 30) 90 description: Recent job history 91 - path: /api/repos 92 method: GET 93 description: Repository sync status 94 - path: /api/system 95 method: GET 96 description: System metrics (local + CI) 97 - path: /api/pipeline/metrics 98 method: GET 99 description: CI pipeline metrics from watcher 100 - path: /api/pipeline/events 101 method: GET 102 description: CI event stream from watcher 103 - path: /api/pipeline/runners 104 method: GET 105 description: Live runner activity from watcher 106 107 troubleshooting: 108 - issue: CI metrics show -- 109 cause: ci-watcher.py not running on CI server 110 fix: ssh devops@ci.ac-dc.network nohup python3 /tmp/ci-watcher.py & 111 112 - issue: Repos show red (no-radicle) 113 cause: Repo not in radicle-repos.json 114 fix: Add repo RID to backend/radicle-repos.json 115 116 - issue: SSH timeout errors 117 cause: CI server unreachable or SSH key issue 118 fix: Verify ssh devops@10.106.0.3 works