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

- [x] Gitea Actions workflows committed
- [x] Deployment automation scripts created
- [x] Gitea Actions runner binary installed
- [x] Systemd service configured
- [x] 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:

```bash
# 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

```bash
# 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