Posted inDevOps

Self-Hosting Woodpecker CI on Docker: A Lightweight and Secure GitHub Actions Alternative

DevOps tutorial - IT technology blog
DevOps tutorial - IT technology blog

The Burden of Heavy CI/CD Pipelines

Running a smooth CI/CD pipeline is non-negotiable for modern software development, but the tools we often rely on come with significant trade-offs. GitHub Actions is excellent for public repositories, but once you move to private, self-managed infrastructure, the costs and privacy concerns start to mount.

On the other hand, heavyweights like GitLab or Jenkins often demand more RAM and CPU than the actual applications they are building. I have encountered many scenarios where a small VPS (Virtual Private Server) with 2GB of RAM would crash simply because the CI/CD controller decided to perform a background task.

This resource-heavy nature is the root cause of many frustrations in the DevOps world. When the tool intended to automate your work becomes a maintenance burden itself, it is time to look for a leaner alternative. Woodpecker CI, a community-fork of Drone CI, solves this by offering a container-native pipeline engine that is remarkably lightweight. It is written in Go, meaning it consumes minimal memory while providing the same YAML-based experience you get from GitHub Actions.

I have applied this approach in production and the results have been consistently stable. By moving away from bloated CI systems to Woodpecker running on Docker, I managed to reduce infrastructure overhead while maintaining full control over the build environment.

Why Woodpecker CI fits your Infrastructure

Before jumping into the commands, it is important to understand why this specific stack works. Woodpecker uses a Server-Agent architecture. The server handles the web interface, user authentication, and API calls, while the agent (or multiple agents) does the heavy lifting of running your build steps inside Docker containers. This separation allows you to scale horizontally by adding more agents on different servers if your build load increases.

Installation: Deploying with Docker Compose

To get started, you need a server with Docker and Docker Compose installed. We will create a centralized directory to store the configuration and database files for Woodpecker.

mkdir ~/woodpecker-ci
cd ~/woodpecker-ci
touch docker-compose.yml .env

Woodpecker requires a secret key to communicate between the server and the agent. Generate one using openssl:

openssl rand -hex 32

Now, let’s configure the docker-compose.yml file. This setup uses SQLite for simplicity, but you can easily switch to PostgreSQL for larger scale projects.

version: '3'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    volumes:
      - ./woodpecker-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
      - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
    ports:
      - "8000:8000"
    restart: always

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    command: agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:8000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
    restart: always
    depends_on:
      - woodpecker-server

Configuration: Connecting to GitHub

To allow Woodpecker to see your repositories, you need to register it as an OAuth Application on GitHub. Navigate to your GitHub Profile -> Settings -> Developer Settings -> OAuth Apps -> New OAuth App.

  • Application Name: My Woodpecker CI
  • Homepage URL: http://your-server-ip:8000
  • Authorization callback URL: http://your-server-ip:8000/authorize

Once registered, you will receive a Client ID and a Client Secret. Fill these into your .env file:

WOODPECKER_HOST=http://your-server-ip:8000
WOODPECKER_AGENT_SECRET=your_generated_hex_key
WOODPECKER_GITHUB_CLIENT=your_github_client_id
WOODPECKER_GITHUB_SECRET=your_github_client_secret

Start the services with a single command:

docker-compose up -d

Creating your First Pipeline

After logging into the Woodpecker UI and enabling your repository, you need to add a configuration file to your project. Woodpecker looks for a file named .woodpecker.yml in the root of your repo. Here is a practical example for a Python project:

pipeline:
  test:
    image: python:3.11-slim
    commands:
      - pip install -r requirements.txt
      - pytest

  build:
    image: docker:24
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    commands:
      - docker build -t my-app:latest .
    when:
      branch: main
      event: push

Notice how every step runs in its own container. This ensures that your build environment is clean every time. Unlike Jenkins, where you often have to manually manage plugins and tool versions on the host machine, Woodpecker keeps everything isolated within Docker images.

Verification and Monitoring

Once you push code to your repository, Woodpecker receives a webhook and starts the pipeline. You can monitor the progress through the web interface. However, from a sysadmin perspective, checking the health of the containers is just as important.

If a pipeline fails to start, the first place to look is the agent logs. The agent is responsible for pulling the images and executing the commands. If it cannot connect to the Docker socket or the server, the logs will tell you immediately:

docker logs -f woodpecker-agent

For long-term stability, I recommend setting up a reverse proxy like Nginx or Traefik with SSL. Running CI/CD over plain HTTP is a security risk, especially when you are passing secrets like Docker Hub credentials or API keys within your pipeline steps. Woodpecker supports secrets management through its UI, allowing you to inject environment variables into your containers without committing them to version control.

Maintaining a self-hosted CI system requires a small amount of discipline. Regularly prune your Docker system on the agent host to prevent old build images from consuming all your disk space. A simple cron job running docker system prune -f once a week is usually enough to keep the system lean and fast.

Share:
Tags: