claudetools/projects/msp-tools/guru-connect/ACTIVATE_CI_CD.md

GuruConnect CI/CD Activation Guide

Date: 2026-01-18 Status: Ready for Activation Server: 172.16.3.30 (gururmm)

---

Prerequisites Complete

• Gitea Actions workflows committed
• Deployment automation scripts created
• Gitea Actions runner binary installed
• Systemd service configured
• All documentation complete

---

Step 1: Register Gitea Actions Runner

1.1 Get Registration Token

1. Open browser and navigate to:

   https://git.azcomputerguru.com/admin/actions/runners
   

2. Log in with Gitea admin credentials

3. Click "Create new Runner"

4. Copy the registration token (starts with something like D0g...)

1.2 Register Runner on Server

# SSH to server
ssh guru@172.16.3.30

# Register runner with token from above
sudo -u gitea-runner act_runner register \
  --instance https://git.azcomputerguru.com \
  --token YOUR_REGISTRATION_TOKEN_HERE \
  --name gururmm-runner \
  --labels ubuntu-latest,ubuntu-22.04

Expected Output:

INFO Registering runner, arch=amd64, os=linux, version=0.2.11.
INFO Successfully registered runner.

1.3 Start Runner Service

# Reload systemd configuration
sudo systemctl daemon-reload

# Enable runner to start on boot
sudo systemctl enable gitea-runner

# Start runner service
sudo systemctl start gitea-runner

# Check status
sudo systemctl status gitea-runner

Expected Output:

● gitea-runner.service - Gitea Actions Runner
     Loaded: loaded (/etc/systemd/system/gitea-runner.service; enabled)
     Active: active (running) since Sat 2026-01-18 16:00:00 UTC

1.4 Verify Registration

1. Go back to: https://git.azcomputerguru.com/admin/actions/runners

2. Verify "gururmm-runner" appears in the list

3. Status should show: Online (green)

---

Step 2: Test Build Workflow

2.1 Trigger First Build

# On server
cd ~/guru-connect

# Make empty commit to trigger CI
git commit --allow-empty -m "test: trigger CI/CD pipeline"
git push origin main

2.2 Monitor Build Progress

1. Open browser: https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions

2. You should see a new workflow run: "Build and Test"

3. Click on the workflow run to view progress

4. Watch the jobs complete:

   • Build Server (Linux) - ~2-3 minutes
   • Build Agent (Windows) - ~2-3 minutes
   • Security Audit - ~1 minute
   • Build Summary - ~10 seconds

2.3 Expected Results

Build Server Job:

✓ Checkout code
✓ Install Rust toolchain
✓ Cache Cargo dependencies
✓ Install dependencies (pkg-config, libssl-dev, protobuf-compiler)
✓ Build server
✓ Upload server binary

Build Agent Job:

✓ Checkout code
✓ Install Rust toolchain
✓ Install cross-compilation tools
✓ Build agent
✓ Upload agent binary

Security Audit Job:

✓ Checkout code
✓ Install Rust toolchain
✓ Install cargo-audit
✓ Run security audit

2.4 Download Build Artifacts

1. Scroll down to Artifacts section

2. Download artifacts:

   • guruconnect-server-linux (server binary)
   • guruconnect-agent-windows (agent .exe)

3. Verify file sizes:

   • Server: ~15-20 MB
   • Agent: ~10-15 MB

---

Step 3: Test Workflow

3.1 Trigger Test Suite

# Tests run automatically on push, or trigger manually:
cd ~/guru-connect

# Make a code change to trigger tests
echo "// Test comment" >> server/src/main.rs
git add server/src/main.rs
git commit -m "test: trigger test workflow"
git push origin main

3.2 Monitor Test Execution

1. Go to: https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions

2. Click on "Run Tests" workflow

3. Watch jobs complete:

   • Test Server - ~3-5 minutes
   • Test Agent - ~2-3 minutes
   • Code Coverage - ~4-6 minutes
   • Lint - ~2-3 minutes

3.3 Expected Results

Test Server Job:

✓ Run unit tests
✓ Run integration tests
✓ Run doc tests

Test Agent Job:

✓ Run agent tests

Code Coverage Job:

✓ Install tarpaulin
✓ Generate coverage report
✓ Upload coverage artifact

Lint Job:

✓ Check formatting (server) - cargo fmt
✓ Check formatting (agent) - cargo fmt
✓ Run clippy (server) - zero warnings
✓ Run clippy (agent) - zero warnings

---

Step 4: Test Deployment Workflow

4.1 Create Version Tag

# On server
cd ~/guru-connect/scripts

# Create first release tag (v0.1.0)
./version-tag.sh patch

Expected Interaction:

=========================================
GuruConnect Version Tagging
=========================================

Current version: v0.0.0
New version: v0.1.0

Changes since v0.0.0:
-------------------------------------------
5b7cf5f ci: add Gitea Actions workflows and deployment automation
[previous commits...]
-------------------------------------------

Create tag v0.1.0? (y/N) y

Updating Cargo.toml versions...
Updated server/Cargo.toml
Updated agent/Cargo.toml

Committing version bump...
[main abc1234] chore: bump version to v0.1.0

Creating tag v0.1.0...
Tag created successfully

To push tag to remote:
  git push origin v0.1.0

4.2 Push Tag to Trigger Deployment

# Push the version bump commit
git push origin main

# Push the tag (this triggers deployment workflow)
git push origin v0.1.0

4.3 Monitor Deployment

1. Go to: https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions

2. Click on "Deploy to Production" workflow

3. Watch deployment progress:

   • Deploy Server - ~10-15 minutes
   • Create Release - ~2-3 minutes

4.4 Expected Deployment Flow

Deploy Server Job:

✓ Checkout code
✓ Install Rust toolchain
✓ Build release binary
✓ Create deployment package
✓ Transfer to server (via SSH)
✓ Run deployment script
  ├─ Backup current version
  ├─ Stop service
  ├─ Deploy new binary
  ├─ Start service
  ├─ Health check
  └─ Verify deployment
✓ Upload deployment artifact

Create Release Job:

✓ Create GitHub/Gitea release
✓ Upload release assets
  ├─ guruconnect-server-v0.1.0.tar.gz
  ├─ guruconnect-agent-v0.1.0.exe
  └─ SHA256SUMS

4.5 Verify Deployment

# Check service status
sudo systemctl status guruconnect

# Check new version
~/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server --version
# Should output: v0.1.0

# Check health endpoint
curl http://172.16.3.30:3002/health
# Should return: {"status":"OK"}

# Check backup created
ls -lh /home/guru/deployments/backups/
# Should show: guruconnect-server-20260118-HHMMSS

# Check artifact saved
ls -lh /home/guru/deployments/artifacts/
# Should show: guruconnect-server-v0.1.0.tar.gz

---

Step 5: Test Manual Deployment

5.1 Download Deployment Artifact

# From Actions page, download: guruconnect-server-v0.1.0.tar.gz
# Or use artifact from server:
cd /home/guru/deployments/artifacts
ls -lh guruconnect-server-v0.1.0.tar.gz

5.2 Run Manual Deployment

cd ~/guru-connect/scripts
./deploy.sh /home/guru/deployments/artifacts/guruconnect-server-v0.1.0.tar.gz

Expected Output:

=========================================
GuruConnect Deployment Script
=========================================

Package: /home/guru/deployments/artifacts/guruconnect-server-v0.1.0.tar.gz
Target: /home/guru/guru-connect

Creating backup...
[OK] Backup created: /home/guru/deployments/backups/guruconnect-server-20260118-161500

Stopping GuruConnect service...
[OK] Service stopped

Extracting deployment package...
Deploying new binary...
[OK] Binary deployed

Archiving deployment package...
[OK] Artifact saved

Starting GuruConnect service...
[OK] Service started successfully

Running health check...
[OK] Health check: PASSED

Deployment version information:
GuruConnect Server v0.1.0

=========================================
Deployment Complete!
=========================================

Deployment time: 20260118-161500
Backup location: /home/guru/deployments/backups/guruconnect-server-20260118-161500
Artifact location: /home/guru/deployments/artifacts/guruconnect-server-20260118-161500.tar.gz

---

Troubleshooting

Runner Not Starting

Symptom: systemctl status gitea-runner shows "inactive" or "failed"

Solution:

# Check logs
sudo journalctl -u gitea-runner -n 50

# Common issues:
# 1. Not registered - run registration command again
# 2. Wrong token - get new token from Gitea admin
# 3. Permissions - ensure gitea-runner user owns /home/gitea-runner/.runner

# Re-register if needed
sudo -u gitea-runner act_runner register \
  --instance https://git.azcomputerguru.com \
  --token NEW_TOKEN_HERE

Workflow Not Triggering

Symptom: Push to main branch but no workflow appears in Actions tab

Checklist:

1. Is runner registered and online? (Check admin/actions/runners)
2. Are workflow files in .gitea/workflows/ directory?
3. Did you push to the correct branch? (main or develop)
4. Are Gitea Actions enabled in repository settings?

Solution:

# Verify workflows committed
git ls-tree -r main --name-only | grep .gitea/workflows

# Should show:
# .gitea/workflows/build-and-test.yml
# .gitea/workflows/deploy.yml
# .gitea/workflows/test.yml

# If missing, add and commit:
git add .gitea/
git commit -m "ci: add missing workflows"
git push origin main

Build Failing

Symptom: Build workflow shows red X

Solution:

# View logs in Gitea Actions tab
# Common issues:

# 1. Missing dependencies
# Add to workflow: apt-get install -y [package]

# 2. Rust compilation errors
# Fix code and push again

# 3. Test failures
# Run tests locally first: cargo test

# 4. Clippy warnings
# Fix warnings: cargo clippy --fix

Deployment Failing

Symptom: Deploy workflow fails or service won't start after deployment

Solution:

# Check deployment logs
cat /home/guru/deployments/deploy-*.log

# Check service logs
sudo journalctl -u guruconnect -n 50

# Manual rollback if needed
ls /home/guru/deployments/backups/
cp /home/guru/deployments/backups/guruconnect-server-TIMESTAMP \
   ~/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server
sudo systemctl restart guruconnect

Health Check Failing

Symptom: Health check returns connection refused or timeout

Solution:

# Check if service is running
sudo systemctl status guruconnect

# Check if port is listening
netstat -tlnp | grep 3002

# Check server logs
sudo journalctl -u guruconnect -f

# Test manually
curl -v http://172.16.3.30:3002/health

# Common issues:
# 1. Service not started - sudo systemctl start guruconnect
# 2. Port blocked - check firewall
# 3. Database connection issue - check .env file

---

Validation Checklist

After completing all steps, verify:

• Runner shows "Online" in Gitea admin panel
• Build workflow completes successfully (green checkmark)
• Test workflow completes successfully (all tests pass)
• Deployment workflow completes successfully
• Service restarts with new version
• Health check returns "OK"
• Backup created in /home/guru/deployments/backups/
• Artifact saved in /home/guru/deployments/artifacts/
• Build artifacts downloadable from Actions tab
• Version tag appears in repository tags
• Manual deployment script works

---

Next Steps After Activation

1. Configure Deployment SSH Keys (Optional)

For fully automated deployment without manual intervention:

# Generate SSH key for runner
sudo -u gitea-runner ssh-keygen -t ed25519 -C "gitea-runner@gururmm"

# Add public key to authorized_keys
sudo -u gitea-runner cat /home/gitea-runner/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys

# Test SSH connection
sudo -u gitea-runner ssh guru@172.16.3.30 whoami

2. Set Up Notification Webhooks (Optional)

Configure Gitea to send notifications on build/deployment events:

1. Go to repository > Settings > Webhooks
2. Add webhook for Slack/Discord/Email
3. Configure triggers: Push, Pull Request, Release

3. Add More Runners (Optional)

For faster builds and multi-platform support:

• Windows Runner: For native Windows agent builds
• macOS Runner: For macOS agent builds
• Staging Runner: For staging environment deployments

4. Enhance CI/CD (Optional)

Performance:

• Add caching for dependencies
• Parallel test execution
• Incremental builds

Quality:

• Code coverage thresholds
• Performance benchmarks
• Security scanning (SAST/DAST)

Deployment:

• Staging environment
• Canary deployments
• Blue-green deployments
• Smoke tests after deployment

---

Quick Reference Commands

# Runner management
sudo systemctl status gitea-runner
sudo systemctl restart gitea-runner
sudo journalctl -u gitea-runner -f

# Create version tag
cd ~/guru-connect/scripts
./version-tag.sh [major|minor|patch]

# Manual deployment
./deploy.sh /path/to/package.tar.gz

# View workflows
https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions

# Check service
sudo systemctl status guruconnect
curl http://172.16.3.30:3002/health

# View logs
sudo journalctl -u guruconnect -f

# Rollback deployment
cp /home/guru/deployments/backups/guruconnect-server-TIMESTAMP \
   ~/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server
sudo systemctl restart guruconnect

---

Support Resources

Gitea Actions Documentation:

• Overview: https://docs.gitea.com/usage/actions/overview
• Workflow Syntax: https://docs.gitea.com/usage/actions/workflow-syntax
• Act Runner: https://gitea.com/gitea/act_runner

Repository:

• https://git.azcomputerguru.com/azcomputerguru/guru-connect

Created Documentation:

• CI_CD_SETUP.md - Complete CI/CD setup guide
• PHASE1_WEEK3_COMPLETE.md - Week 3 completion summary
• ACTIVATE_CI_CD.md - This guide

---

Last Updated: 2026-01-18 Status: Ready for Activation Action Required: Register Gitea Actions runner with admin token