184 lines
5.3 KiB
Markdown
184 lines
5.3 KiB
Markdown
# 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
|
|
```
|