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

<!-- Document created on 2026-01-18 -->
# GuruConnect CI/CD Setup Guide

**Version:** Phase 1 Week 3
**Status:** Ready for Installation
**CI Platform:** Gitea Actions

---

## Overview

Automated CI/CD pipeline for GuruConnect using Gitea Actions:

- **Automated Builds** - Build server and agent on every commit
- **Automated Tests** - Run unit, integration, and security tests
- **Automated Deployment** - Deploy to production on version tags
- **Build Artifacts** - Store and version all build outputs
- **Version Tagging** - Automated semantic versioning

---

## Architecture

```
┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Git Push  │─────>│ Gitea Actions│─────>│   Deploy    │
│             │      │   Workflows   │      │  to Server  │
└─────────────┘      └──────────────┘      └─────────────┘
                            │
                            ├─ Build Server (Linux)
                            ├─ Build Agent (Windows)
                            ├─ Run Tests
                            ├─ Security Audit
                            └─ Create Artifacts
```

---

## Workflows

### 1. Build and Test (`build-and-test.yml`)

**Triggers:**
- Push to `main` or `develop` branches
- Pull requests to `main`

**Jobs:**
- Build Server (Linux x86_64)
- Build Agent (Windows x86_64)
- Security Audit (cargo audit)
- Upload Artifacts (30-day retention)

**Artifacts:**
- `guruconnect-server-linux` - Server binary
- `guruconnect-agent-windows` - Agent binary (.exe)

### 2. Run Tests (`test.yml`)

**Triggers:**
- Push to any branch
- Pull requests

**Jobs:**
- Unit Tests (server & agent)
- Integration Tests
- Code Coverage
- Linting & Formatting

**Artifacts:**
- Coverage reports (XML)

### 3. Deploy to Production (`deploy.yml`)

**Triggers:**
- Push tags matching `v*.*.*` (e.g., v0.1.0)
- Manual workflow dispatch

**Jobs:**
- Build release version
- Create deployment package
- Deploy to production server (172.16.3.30)
- Create GitHub release
- Upload release assets

**Artifacts:**
- Deployment packages (90-day retention)

---

## Installation Steps

### 1. Install Gitea Actions Runner

```bash
# On the RMM server (172.16.3.30)
ssh guru@172.16.3.30

cd ~/guru-connect/scripts
sudo bash install-gitea-runner.sh
```

### 2. Register the Runner

```bash
# Get registration token from Gitea:
# https://git.azcomputerguru.com/admin/actions/runners

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

### 3. Start the Runner Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner
```

### 4. Upload Workflow Files

```bash
# From local machine
cd D:\ClaudeTools\projects\msp-tools\guru-connect

# Copy workflow files to server
scp -r .gitea guru@172.16.3.30:~/guru-connect/

# Copy scripts to server
scp scripts/deploy.sh guru@172.16.3.30:~/guru-connect/scripts/
scp scripts/version-tag.sh guru@172.16.3.30:~/guru-connect/scripts/

# Make scripts executable
ssh guru@172.16.3.30 "cd ~/guru-connect/scripts && chmod +x *.sh"
```

### 5. Commit and Push Workflows

```bash
# On server
ssh guru@172.16.3.30
cd ~/guru-connect

git add .gitea/ scripts/
git commit -m "ci: add Gitea Actions workflows and deployment automation"
git push origin main
```

---

## Usage

### Triggering Builds

**Automatic:**
- Push to `main` or `develop` → Runs build + test
- Create pull request → Runs all tests
- Push version tag → Deploys to production

**Manual:**
- Go to repository > Actions
- Select workflow
- Click "Run workflow"

### Creating a Release

```bash
# Use the version tagging script
cd ~/guru-connect/scripts
./version-tag.sh patch    # Bump patch version (0.1.0 → 0.1.1)
./version-tag.sh minor    # Bump minor version (0.1.1 → 0.2.0)
./version-tag.sh major    # Bump major version (0.2.0 → 1.0.0)

# Push tag to trigger deployment
git push origin main
git push origin v0.1.1
```

### Manual Deployment

```bash
# Deploy from artifact
cd ~/guru-connect/scripts
./deploy.sh /path/to/guruconnect-server-v0.1.0.tar.gz

# Deploy latest
./deploy.sh /home/guru/deployments/artifacts/guruconnect-server-latest.tar.gz
```

---

## Monitoring

### View Workflow Runs

```
https://git.azcomputerguru.com/azcomputerguru/guru-connect/actions
```

### Check Runner Status

```bash
# On server
sudo systemctl status gitea-runner

# View logs
sudo journalctl -u gitea-runner -f

# In Gitea
https://git.azcomputerguru.com/admin/actions/runners
```

### View Build Artifacts

```
Repository > Actions > Workflow Run > Artifacts section
```

---

## Deployment Process

### Automated Deployment Flow

1. **Tag Creation** - Developer creates version tag
2. **Workflow Trigger** - `deploy.yml` starts automatically
3. **Build** - Compiles release binary
4. **Package** - Creates deployment tarball
5. **Transfer** - Copies to server (via SSH)
6. **Backup** - Saves current binary
7. **Stop Service** - Stops GuruConnect systemd service
8. **Deploy** - Extracts and installs new binary
9. **Start Service** - Restarts systemd service
10. **Health Check** - Verifies server is responding
11. **Rollback** - Automatic if health check fails

### Deployment Locations

```
Backups:    /home/guru/deployments/backups/
Artifacts:  /home/guru/deployments/artifacts/
Deploy Dir: /home/guru/guru-connect/
```

### Rollback

```bash
# List backups
ls -lh /home/guru/deployments/backups/

# Rollback to specific version
cp /home/guru/deployments/backups/guruconnect-server-TIMESTAMP \
   ~/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server

sudo systemctl restart guruconnect
```

---

## Configuration

### Secrets (Required)

Configure in Gitea repository settings:

```
Repository > Settings > Secrets
```

**Required Secrets:**
- `SSH_PRIVATE_KEY` - SSH key for deployment to 172.16.3.30
- `SSH_HOST` - Deployment server host (172.16.3.30)
- `SSH_USER` - Deployment user (guru)

### Environment Variables

```yaml
# In workflow files
env:
  CARGO_TERM_COLOR: always
  RUSTFLAGS: "-D warnings"
  DEPLOY_SERVER: "172.16.3.30"
  DEPLOY_USER: "guru"
```

---

## Troubleshooting

### Runner Not Starting

```bash
# Check status
sudo systemctl status gitea-runner

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

# Verify registration
sudo -u gitea-runner cat /home/gitea-runner/.runner/.runner

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

### Workflow Failing

**Check logs in Gitea:**
1. Go to Actions tab
2. Click on failed run
3. View job logs

**Common Issues:**
- Missing dependencies → Add to workflow
- Rust version mismatch → Update toolchain version
- Test failures → Fix tests before merging

### Deployment Failing

```bash
# Check deployment logs on server
cat /home/guru/deployments/deploy-TIMESTAMP.log

# Verify service status
sudo systemctl status guruconnect

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

# Manual deployment
cd ~/guru-connect/scripts
./deploy.sh /path/to/package.tar.gz
```

### Artifacts Not Uploading

**Check retention settings:**
- Build artifacts: 30 days
- Deployment packages: 90 days

**Check storage:**
```bash
# On Gitea server
df -h
du -sh /var/lib/gitea/data/actions_artifacts/
```

---

## Security

### Runner Security

- Runner runs as dedicated `gitea-runner` user
- Limited permissions (no sudo)
- Isolated working directory
- Automatic cleanup after jobs

### Deployment Security

- SSH key-based authentication
- Automated backups before deployment
- Health checks before considering deployment successful
- Automatic rollback on failure
- Audit trail in deployment logs

### Artifact Security

- Artifacts stored with limited retention
- Accessible only to repository collaborators
- Build artifacts include checksums

---

## Performance

### Build Times (Estimated)

- Server build: ~2-3 minutes
- Agent build: ~2-3 minutes
- Tests: ~1-2 minutes
- Total pipeline: ~5-8 minutes

### Caching

Workflows use cargo cache to speed up builds:
- Cache hit: ~1 minute
- Cache miss: ~2-3 minutes

### Concurrent Builds

- Multiple workflows can run in parallel
- Limited by runner capacity (1 runner = 1 job at a time)

---

## Maintenance

### Runner Updates

```bash
# Stop runner
sudo systemctl stop gitea-runner

# Download new version
RUNNER_VERSION="0.2.12"  # Update as needed
cd /tmp
wget https://dl.gitea.com/act_runner/${RUNNER_VERSION}/act_runner-${RUNNER_VERSION}-linux-amd64
sudo mv act_runner-* /usr/local/bin/act_runner
sudo chmod +x /usr/local/bin/act_runner

# Restart runner
sudo systemctl start gitea-runner
```

### Cleanup Old Artifacts

```bash
# Manual cleanup on server
rm /home/guru/deployments/backups/guruconnect-server-$(date -d '90 days ago' +%Y%m%d)*
rm /home/guru/deployments/artifacts/guruconnect-server-$(date -d '90 days ago' +%Y%m%d)*
```

### Monitor Disk Usage

```bash
# Check deployment directories
du -sh /home/guru/deployments/*

# Check runner cache
du -sh /home/gitea-runner/.cache/act/
```

---

## Best Practices

### Branching Strategy

```
main        - Production-ready code
develop     - Integration branch
feature/*   - Feature branches
hotfix/*    - Emergency fixes
```

### Version Tagging

- Use semantic versioning: `vMAJOR.MINOR.PATCH`
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes

### Commit Messages

```
feat: Add new feature
fix: Fix bug
docs: Update documentation
ci: CI/CD changes
chore: Maintenance tasks
test: Add/update tests
```

### Testing Before Merge

1. All tests must pass
2. No clippy warnings
3. Code formatted (cargo fmt)
4. Security audit passed

---

## Future Enhancements

### Phase 2 Improvements

- Add more test runners (Windows, macOS)
- Implement staging environment
- Add smoke tests post-deployment
- Configure Slack/email notifications
- Add performance benchmarking
- Implement canary deployments
- Add Docker container builds

### Monitoring Integration

- Send build metrics to Prometheus
- Grafana dashboard for CI/CD metrics
- Alert on failed deployments
- Track build duration trends

---

## Reference Commands

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

# Deployment
cd ~/guru-connect/scripts
./deploy.sh <package.tar.gz>

# Version tagging
./version-tag.sh [major|minor|patch]

# Manual build
cd ~/guru-connect
cargo build --release --target x86_64-unknown-linux-gnu

# View artifacts
ls -lh /home/guru/deployments/artifacts/

# View backups
ls -lh /home/guru/deployments/backups/
```

---

## Support

**Documentation:**
- Gitea Actions: https://docs.gitea.com/usage/actions/overview
- Act Runner: https://gitea.com/gitea/act_runner

**Repository:**
- https://git.azcomputerguru.com/azcomputerguru/guru-connect

**Contact:**
- Open issue in Gitea repository

---

**Last Updated:** 2026-01-18
**Phase:** 1 Week 3 - CI/CD Automation
**Status:** Ready for Installation