Posted inFedora

Installing Woodpecker CI on Fedora Server: A Lightweight CI/CD Solution for Gitea

Fedora tutorial - IT technology blog
Fedora tutorial - IT technology blog

Woodpecker CI: When Jenkins is Too Resource-Intensive for Your Needs

If you’re running a VPS with modest specs (e.g., 2 vCPUs and 2GB RAM), installing Jenkins can be a nightmare. Jenkins runs on Java and typically consumes at least 1GB of RAM right at startup. For small projects that only need to build Docker images or deploy static websites, Woodpecker CI is a much smarter alternative. I’ve been running Fedora Server for personal projects for over two years and found Woodpecker CI to be the missing piece to optimize the DevOps workflow.

Woodpecker inherits the best parts of Drone CI from its fully open-source era. Written in Go, this system runs extremely smoothly as a container and pairs very quickly with Gitea.

Real-world Comparison: Why Choose Woodpecker?

Before diving into the configuration, let’s look at some real-world numbers to see the difference between popular tools:

  • Jenkins: Full-featured but heavy. Requires at least 2GB of RAM for stable operation. Groovy Pipeline configuration can be quite complex for beginners.
  • GitLab CI: Excellent but comes with a massive GitLab codebase. If self-hosting, you need at least 4GB-8GB of RAM for the entire system.
  • GitHub Actions: Convenient but entirely cloud-dependent. You’ll face challenges if you want to deploy on-premise to secure internal code.
  • Woodpecker CI: Uses YAML (similar to GitHub Actions). Woodpecker Server only consumes about 100MB – 200MB of RAM. This is an ideal figure for low-spec servers.

Pros and Cons to Consider

Pros:

  • Near-instant startup.
  • Fully open-source (Apache 2.0), no worries about paid feature limitations.
  • Intuitive Pipeline configuration via the .woodpecker.yml file.
  • Excellent support for Gitea, Forgejo, GitHub, and GitLab.

Cons:

  • Fewer plugins than Jenkins. However, it still meets 95% of standard build/deploy needs.
  • The support community is not yet as large as other major tools.

The Power of Combining Fedora Server and Woodpecker

Fedora Server is always at the forefront with the latest Kernel and built-in Podman. Instead of using Docker, Podman on Fedora provides better security through SELinux. Deploying Woodpecker on this platform allows you to leverage the stability of the latest container builds without needing excessive fine-tuning.

Step 1: Set Up OAuth Application on Gitea

To allow Woodpecker to access your repositories, you need to create a secure bridge on Gitea:

  1. Access Gitea, go to Settings -> Applications.
  2. Under Manage OAuth2 Applications, name the application Woodpecker CI.
  3. Redirect URI: Enter your server address in the format: https://ci.yourdomain.com/authorize.
  4. After clicking Create Application, copy the Client ID and Client Secret to a note file. We will need them for the server configuration step.

Step 2: Prepare the Podman Environment on Fedora

Fedora Server comes with Podman, but we need to add podman-compose and enable the socket so the Agent can communicate with the system.

sudo dnf update -y
sudo dnf install podman podman-compose -y

# Enable the socket so Woodpecker Agent has permission to create build containers
sudo systemctl enable --now podman.socket

Check the socket status with the command: ls -al /run/podman/podman.sock. If you see the socket file appear, you’ve succeeded.

Step 3: Deploy Woodpecker Using Podman Compose

We will bundle both the Server and Agent into a single file for easy management. Create the working directory:

mkdir ~/woodpecker && cd ~/woodpecker
nano docker-compose.yml

Paste the following configuration into the file. Be sure to change the environment variables to match the OAuth information you just created:

version: '3'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    volumes:
      - ./woodpecker-data:/var/lib/woodpecker/
    environment:
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=https://git.yourdomain.com
      - WOODPECKER_GITEA_CLIENT=YOUR_CLIENT_ID
      - WOODPECKER_GITEA_SECRET=YOUR_CLIENT_SECRET
      - WOODPECKER_SERVER_ADDR=:8000
      - WOODPECKER_AGENT_SECRET=your_secure_random_string
    ports:
      - 8000:8000
    restart: always

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    command: agent
    volumes:
      - /run/podman/podman.sock:/var/run/docker.sock
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=your_secure_random_string
      - WOODPECKER_BACKEND=docker
    restart: always
    depends_on:
      - woodpecker-server

Pro tip regarding SELinux: Fedora is very strict about socket access. If you encounter a Permission Denied error, run the following command to allow containers to manage cgroups:

sudo setsebool -P container_manage_cgroup on

Start the system with the command: podman-compose up -d.

Step 4: Enable the Pipeline for Your Project

Open your browser and navigate to port 8000 of your server. Log in using your Gitea account. In the dashboard, you will see all your existing repositories.

Just click Enable on the desired repo. Woodpecker will automatically set up the Webhook on the Gitea side. From this moment on, every time you push code, a build process will automatically start.

Step 5: Create a Sample Pipeline Definition File

Create a .woodpecker.yml file in the root directory of your Node.js project to test the functionality:

pipeline:
  test:
    image: node:18-alpine
    commands:
      - npm install
      - npm test

  build-image:
    image: plugins/docker
    settings:
      repo: registry.yourdomain.com/my-app
      registry: registry.yourdomain.com
      username:
        from_secret: docker_user
      password:
        from_secret: docker_pass
    when:
      event: push
      branch: main

When you push this file to the main branch, the Woodpecker Agent will automatically pull the Node.js image to run tests. If everything is stable, it will proceed to build and push the image to your registry.

Real-world Operational Experience

After using Woodpecker on Fedora for a while, I’ve summarized three important takeaways:

  1. Free up disk space: Build containers often leave behind dangling images. You should set up a cronjob to run podman image prune -f weekly to avoid filling up the storage.
  2. Secure Secrets: Never write passwords directly into the YAML file. Use the Secrets feature in the Repo settings on the Woodpecker Web UI.
  3. Speed up builds with Cache: For larger projects, use a cache plugin to save the node_modules or vendor directories. This can reduce build times from 5 minutes to less than 1 minute.

The combination of Woodpecker CI and Fedora Server provides a highly professional DevOps environment with nearly zero operating costs. Good luck with your installation!

Share:
Tags: