# CI/CD Setup with Woodpecker

This document describes how to set up and use Woodpecker CI/CD for the Copper Tone Technologies platform.

## Overview

Woodpecker CI is a community-driven fork of Drone CI that integrates seamlessly with Gitea. Our setup includes:

- **Woodpecker Server**: Web UI and coordination
- **Woodpecker Agent**: Executes pipeline steps using Podman

## Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│     Gitea       │────▶│ Woodpecker Server│────▶│ Woodpecker Agent│
│ git.coppertone  │     │  ci.coppertone   │     │   (Podman)      │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                        │                        │
        │   Webhook on push      │   Coordinates jobs     │   Runs containers
        └────────────────────────┴────────────────────────┘
```

## Pipeline Stages

### Pull Requests
- Frontend lint and type-check
- Frontend unit tests
- Backend Go tests for all services

### Develop Branch → Testing Environment
1. Run all tests
2. Build frontend
3. SSH deploy to testing server
4. Notify on completion

### Testing Branch → Staging Environment
1. Full test suite
2. SSH deploy to staging server

### Main Branch → Production Environment
1. Full test suite
2. Security scan (Trivy)
3. SSH deploy to production
4. Create version tag
5. Notify stakeholders

## Setup Instructions

### 1. Create Gitea OAuth Application

1. Log into Gitea as admin
2. Go to **Settings** → **Applications**
3. Click **Create a new OAuth2 Application**
4. Fill in:
   - **Application Name**: `Woodpecker CI`
   - **Redirect URI**: `https://ci.coppertone.tech/authorize`
5. Save the **Client ID** and **Client Secret**

### 2. Configure Environment

```bash
cd infrastructure
cp .env.ci.example .env.ci

# Generate agent secret
AGENT_SECRET=$(openssl rand -hex 32)
echo "WOODPECKER_AGENT_SECRET=$AGENT_SECRET" >> .env.ci

# Edit .env.ci with your Gitea OAuth credentials
nano .env.ci
```

### 3. Start Woodpecker

```bash
cd infrastructure
podman-compose -f docker-compose.ci.yml --env-file .env.ci up -d
```

### 4. Configure Woodpecker Secrets

In the Woodpecker UI (https://ci.coppertone.tech), add these secrets for your repository:

| Secret Name | Description |
|-------------|-------------|
| `testing_server_host` | Testing server hostname/IP |
| `testing_server_user` | SSH username for testing server |
| `testing_server_ssh_key` | SSH private key for testing server |
| `staging_server_host` | Staging server hostname/IP |
| `staging_server_user` | SSH username for staging server |
| `staging_server_ssh_key` | SSH private key for staging server |
| `production_server_host` | Production server hostname/IP |
| `production_server_user` | SSH username for production server |
| `production_server_ssh_key` | SSH private key for production server |
| `notification_webhook` | Webhook URL for notifications (optional) |

### 5. Enable Repository

1. Go to Woodpecker UI
2. Click **Add repository**
3. Select `CopperTone.Tech` from the list
4. Enable the repository

## Pipeline Configuration

The pipeline is defined in `.woodpecker.yml` at the repository root.

### Key Features

- **Multi-document YAML**: Separate pipelines for different branches/events
- **Parallel execution**: Tests run in parallel for faster feedback
- **Conditional deployment**: Only deploys on specific branches
- **Secret management**: Sensitive data stored in Woodpecker secrets

### Customizing the Pipeline

Edit `.woodpecker.yml` to:
- Add new services to test
- Change deployment targets
- Add additional checks (security, performance)

## Troubleshooting

### Agent Can't Connect to Server

Check that both containers are on the same network:
```bash
podman network inspect woodpecker-network
```

### Podman Socket Not Found

For rootless Podman:
```bash
systemctl --user enable --now podman.socket
```

For root Podman:
```bash
sudo systemctl enable --now podman.socket
```

### Build Fails with Permission Denied

Ensure the agent has access to the Podman socket:
```bash
ls -la /run/user/1000/podman/podman.sock
```

### Webhook Not Triggering

1. Check Gitea webhook configuration
2. Verify Woodpecker server is accessible from Gitea
3. Check Woodpecker server logs:
   ```bash
   podman logs woodpecker-server
   ```

## Monitoring

View pipeline status:
- **Woodpecker UI**: https://ci.coppertone.tech
- **Logs**: `podman logs woodpecker-server` / `podman logs woodpecker-agent`

## Security Considerations

1. **Secrets**: Never commit secrets to the repository
2. **SSH Keys**: Use dedicated deploy keys with minimal permissions
3. **Agent Isolation**: Consider running agents in isolated environments
4. **Webhook Security**: Woodpecker validates webhook signatures from Gitea

## Backup

Backup the Woodpecker data volume:
```bash
podman volume export woodpecker-server-data > woodpecker-backup.tar
```

Restore:
```bash
podman volume import woodpecker-server-data < woodpecker-backup.tar
```