Self-Hosting Woodpecker CI on a VPS: The Ultra-Lightweight CI/CD Tool Requiring Under 100MB RAM

Introduction: The Hidden Cost of Modern CI/CD Pipelines

In the modern DevOps landscape, Continuous Integration and Continuous Deployment (CI/CD) have transitioned from luxury frameworks to absolute necessities. However, for startups, independent developers, and small-to-medium enterprises (SMEs), running standard CI/CD infrastructure can introduce a steep financial and resource overhead. Industry giants like Jenkins or self-hosted GitLab Runners are notoriously resource-hungry, often demanding gigabytes of RAM just to sit idle in a container environment.

When operating on a budget Virtual Private Server (VPS)—such as an entry-tier 1GB RAM instance—allocating half of your system resources purely to a deployment runner is unsustainable. This is where Woodpecker CI enters the equation. As a community-driven fork of the popular Drone CI framework, Woodpecker CI delivers a highly scalable, secure, container-first automation platform that operates seamlessly on a fraction of the resource footprint. In fact, a fully functional server and runner setup routinely consumes less than 100MB of RAM.

This comprehensive guide will walk you through the architectural advantages of Woodpecker CI and provide a step-by-step blueprint to self-host it on your own VPS using Docker Compose.

---

Why Woodpecker CI? The Case for Ultra-Lightweight Automation

Before diving into the technical implementation, it is critical to understand why Woodpecker CI is uniquely suited for resource-constrained environments compared to traditional alternatives.

1. Exceptional Resource Efficiency

Traditional CI engines are built on heavy runtimes or enterprise Java stacks that demand significant baseline memory. Woodpecker CI is written entirely in Go, a language celebrated for its compiled efficiency, minimal memory footprint, and rapid execution speeds. The entire ecosystem is split into two lightweight components: the Server and the Agent. This decoupled design ensures that idle processes consume virtually zero overhead.

2. Strict Container-First Architecture

Every step within a Woodpecker pipeline executes inside an isolated Docker container. This guarantees environment consistency across local development and production runners. If your pipeline requires a specific version of Node.js, Python, or Go, you simply define the official Docker image for that step. There is no need to manually configure dependencies or manage conflicting runtimes on the host OS.

3. Seamless Declarative Configuration

Pipelines are configured using a single declarative YAML file (.woodpecker.yml) placed at the root of your repository. This approach aligns perfectly with the GitOps philosophy, ensuring that your infrastructure-as-code evolves concurrently with your application source code. The syntax is exceptionally clean and highly intuitive for anyone previously exposed to GitHub Actions or Drone CI.

---

Prerequisites for Self-Hosting

To follow this tutorial, ensure your environment meets the following baseline requirements:

• A VPS Instance: A Linux-based VPS (Ubuntu 22.04 LTS or newer recommended). Even a 1 vCPU, 1GB RAM server is more than sufficient.
• A Domain Name: A domain or subdomain (e.g., ci.yourcompany.com) pointed to your VPS IP address with proper A records.
• Docker and Docker Compose: Installed and configured on the host machine.
• A Git Provider: An administrative account on a Git platform (GitHub, GitLab, Gitea, or Forgejo) to authenticate users and trigger webhooks.

---

Step 1: Registering an OAuth Application with Your Git Provider

Woodpecker CI relies entirely on your Git provider for user authentication and access control. In this guide, we will use GitHub as our reference provider, though the process is highly analogous for GitLab or Gitea.

1. Navigate to your GitHub account settings, scroll down to Developer Settings, and select OAuth Apps.
2. Click New OAuth App and populate the configuration fields as follows:
• Application Name: Woodpecker CI Server
• Homepage URL: [https://ci.yourdomain.com](https://ci.yourdomain.com)
• Authorization callback URL: [https://ci.yourdomain.com/authorize](https://ci.yourdomain.com/authorize)
3. Click Register Application.
4. Copy the generated Client ID and click Generate a new client secret. Securely save both tokens; they are mandatory for the server initialization phase.

Security Note: Always ensure that the Authorization Callback URL precisely matches your external domain scheme (HTTPS is highly recommended for production setups).

---

Step 2: Designing the Docker Compose Configuration

We will configure Woodpecker CI using a multi-container Docker Compose file. This setup links the Woodpecker Server (which handles the UI, API, and webhook orchestration) with the Woodpecker Agent (the worker component that executes the actual pipeline steps).

Create a dedicated directory on your VPS and initialize your configuration file:

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

Insert the following structured configuration into the file:

version: '3.8'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    ports:
      - "8000:8000"
    volumes:
      - ./woodpecker-server-data:/var/lib/woodpecker
    environment:
      - WOODPECKER_HOST=[https://ci.yourdomain.com](https://ci.yourdomain.com)
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=your_github_client_id
      - WOODPECKER_GITHUB_SECRET=your_github_client_secret
      - WOODPECKER_AGENT_SECRET=a_long_random_secure_string_here
      - WOODPECKER_OPEN=true
    restart: always

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

Key Environment Variables Explained:

• WOODPECKER_HOST: The external web address where your users and webhooks will access the UI.
• WOODPECKER_AGENT_SECRET: A shared cryptographic token used to secure communication between the server and the agent. Generate a unique string using openssl rand -hex 32.
• WOODPECKER_OPEN: When set to true, this allows any user authenticated via your Git provider to register on your instance. Set this to false after initial login if you want to restrict access to unauthorized public users.

---

Step 3: Setting Up a Reverse Proxy (Nginx) and SSL

To safely expose Woodpecker CI over port 443 with modern SSL/TLS encryption, setting up a reverse proxy like Nginx combined with Let's Encrypt is standard best practice.

Install Nginx and Certbot on your host system:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx -y

Configure a new Nginx server block for Woodpecker:

sudo nano /etc/nginx/sites-available/woodpecker

Add the following configuration block:

server {
    listen 80;
    server_name ci.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 90;
    }
}

Enable the site configuration, test for syntax errors, and reload Nginx:

sudo ln -s /etc/nginx/sites-available/woodpecker /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Finally, secure your domain with an automated Let's Encrypt SSL certificate:

sudo certbot --nginx -d ci.yourdomain.com

---

Step 4: Launching Woodpecker and Validating Memory Footprint

With all configuration files safely in place, you can now launch your ultra-lightweight CI/CD environment with Docker Compose:

docker compose up -d

Verify that both containers are running without anomalies by reviewing the real-time logs:

docker compose logs -f

To objectively verify Woodpecker's remarkable memory efficiency, run the standard Docker resource monitoring command:

docker stats --no-stream

You will observe a metrics report highly reminiscent of the following output:

Container Name	CPU %	Memory Usage	Memory Limit
woodpecker-server	0.02%	34.5 MiB	990 MiB
woodpecker-agent	0.01%	18.2 MiB	990 MiB

Combined, the active environment utilizes roughly 53 MiB of RAM while sitting idle. Even during intensive pipeline execution, the core components maintain strict memory hygiene, passing the heavy computational weight directly to the temporary, short-lived pipeline containers.

---

Step 5: Writing Your First Woodpecker Pipeline File

To validate the installation, log into your new web dashboard via [https://ci.yourdomain.com](https://ci.yourdomain.com), authenticate with GitHub, and enable one of your repositories. Once enabled, add a .woodpecker.yml configuration file to the root of that repository to construct a basic testing pipeline.

pipeline:
  test:
    image: node:20-alpine
    commands:
      - node --version
      - npm --version

  build:
    image: alpine:latest
    commands:
      - echo "Compiling and building assets successfully completed!"

Commit this file and push it directly to your remote repository. Woodpecker will capture the webhook event sent by GitHub instantly, spinning up isolated containers on your VPS to execute your tasks sequentially, and reporting the final build status back to your Git interface.

---

Conclusion

Self-hosting your CI/CD infrastructure does not require high monthly financial outlays or massive, resource-heavy servers. Woodpecker CI proves that modern automation can be incredibly robust while maintaining an astonishingly low digital footprint. By leveraging its Go-compiled architecture and container-first mechanics, developers can seamlessly unlock full enterprise-grade orchestration on entry-level, budget-friendly VPS setups. Scale your automation, protect your privacy, and maximize your system resources all with one ultra-efficient tool.