Woodpecker CI on an Offshore VPS

Drone CI moved to a source-available license in 2020, and while the core stayed open, several features became commercial-only. Woodpecker forked from the last fully open-source Drone release and has been actively maintained by the community since. The pipeline syntax stays nearly identical - existing `.drone.yml` files work as `.woodpecker.yml` with minor adjustments. If you ran Drone and want to stay on a fully Apache 2.0 licensed stack, Woodpecker is the drop-in replacement. The other reason to choose Woodpecker is governance. The project is community-driven with no commercial entity behind it. There is no license risk down the road. For teams running CI on offshore infrastructure as part of a broader effort to control their tooling stack, this matters - a sudden license change from a single corporate maintainer can force a migration at the worst possible moment. Feature parity with Drone OSS is essentially complete, and Woodpecker has added several improvements - better Postgres support, improved web UI, simpler agent registration, and a more flexible plugin model. For most teams there is no functional reason to prefer Drone over Woodpecker today.

Woodpecker uses the same server-plus-agent architecture as Drone. The server is a single Go binary that handles OAuth with your git provider, receives webhooks, schedules pipelines, and serves the web UI. Agents are separate Go binaries (or containers) that connect to the server via gRPC, pull jobs, and execute pipeline steps in Docker containers. For a team of 5 to 15 active developers, a single VPS with 2 vCPU and 4 GB RAM hosts both the server and one agent process comfortably. The server itself uses about 100 MB RAM at idle. Each running pipeline step consumes resources based on what is in the container image - a typical npm test runs in 500 MB to 1 GB, a Maven build closer to 2 GB. Run 2 to 4 agent slots in parallel on this size of VPS. Disk usage is mostly Docker images and build artifacts. Container images for common base layers (node, golang, python, alpine) compound quickly - a 100 GB disk fills in a few months without pruning. Run `docker system prune` weekly via cron and configure short artifact retention on Woodpecker itself. For larger teams, add a separate agent-only VPS - the server stays on a small VPS and the heavy lifting happens on a beefy 8 GB or 16 GB RAM box.

Install Docker: `curl -fsSL https://get.docker.com | sh`. Create a docker-compose file at `/opt/woodpecker/docker-compose.yml` with two services. The server: `image: woodpeckerci/woodpecker-server:latest`, environment vars `WOODPECKER_OPEN=false`, `WOODPECKER_HOST=https://ci.yourdomain.tld`, `WOODPECKER_GITEA=true`, `WOODPECKER_GITEA_URL=https://gitea.yourdomain.tld`, `WOODPECKER_GITEA_CLIENT=oauth-client-id`, `WOODPECKER_GITEA_SECRET=oauth-client-secret`, `WOODPECKER_AGENT_SECRET=YOUR_RANDOM_HEX`, ports 8000 mapped to host. Mount `./server-data:/var/lib/woodpecker` for state persistence. The agent: `image: woodpeckerci/woodpecker-agent:latest`, environment `WOODPECKER_SERVER=woodpecker-server:9000`, `WOODPECKER_AGENT_SECRET=YOUR_RANDOM_HEX` (same as server), `WOODPECKER_MAX_WORKFLOWS=4`. Mount `/var/run/docker.sock:/var/run/docker.sock` so the agent can spawn pipeline containers via Docker. Restart policy `unless-stopped` on both. Run `docker compose up -d`. Put Caddy or Nginx with TLS in front of port 8000. In Gitea (or your git provider of choice), create an OAuth application pointing at `https://ci.yourdomain.tld/authorize` and paste the client id/secret into the env. Log in to Woodpecker via OAuth, activate a repository, push a commit with a `.woodpecker.yml` file, and the pipeline runs within seconds.