web-hosts/domains/coppertone.tech/docs/CI-CD-Setup.md

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

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

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:

podman network inspect woodpecker-network

Podman Socket Not Found

For rootless Podman:

systemctl --user enable --now podman.socket

For root Podman:

sudo systemctl enable --now podman.socket

Build Fails with Permission Denied

Ensure the agent has access to the Podman socket:

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:

   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:

podman volume export woodpecker-server-data > woodpecker-backup.tar

Restore:

podman volume import woodpecker-server-data < woodpecker-backup.tar