DPTCloud
Back to articles
Technology Insight

Deploying Woodpecker CI on a VPS: A Lightweight, Docker-Powered Continuous Integration System

June 1, 2026

Introduction to Modern, Lightweight CI/CD

In the contemporary software development lifecycle, Continuous Integration and Continuous Deployment (CI/CD) have transitioned from luxury practices to absolute necessities. However, for independent developers, startups, and small-to-medium enterprises (SMEs), traditional CI/CD platforms can present significant hurdles. Heavyweight tools like Jenkins or self-hosted GitLab CI instances demand substantial server resources, often requiring multiple gigabytes of RAM just to idle. This resource hogging translates directly to higher monthly Virtual Private Server (VPS) costs.

Enter Woodpecker CI. Forged as a community-driven fork of Drone CI, Woodpecker CI is a next-generation, ultra-lightweight automation engine designed specifically to run inside Docker containers. It delivers the declarative, pipeline-as-code flexibility developers love, but with a drastically reduced footprint. If you are looking to turn a modest, budget-friendly VPS into a lean, mean deployment machine, Woodpecker CI combined with Docker is the ultimate solution.

Why Woodpecker CI is Ideal for VPS Environments

When deploying infrastructure on a VPS, resource efficiency directly impacts your bottom line. Woodpecker CI excels in this environment for several key reasons:

  • Minimal Resource Footprint: While alternative platforms might require 2GB to 4GB of RAM as a baseline, the Woodpecker server and agent combined can comfortably operate on less than 200MB of RAM when idle.
  • Docker-First Architecture: Every pipeline step in Woodpecker runs inside its own isolated Docker container. This ensures that your build environments are completely clean, reproducible, and decoupled from the host OS.
  • Strict Agent-Server Separation: Woodpecker splits its architecture into a centralized server (which handles orchestration and webhooks) and lightweight agents (which execute the actual workloads). This allows you to scale by placing agents on separate, specialized servers if your build demands grow.
  • Native Git Platform Integration: It seamlessly hooks into popular Git hosting services including GitHub, GitLab, Gitea, and Forgejo, providing instant feedback on pull requests and commits.

Prerequisites for Deployment

Before proceeding with the installation, ensure your environment meets the following baseline criteria:

  1. A Linux-based VPS (Ubuntu 22.04 LTS or 24.04 LTS recommended) with a public IP address.
  2. Docker and the Docker Compose plugin installed on the host machine.
  3. A fully qualified domain name (FQDN) pointed to your VPS IP address (e.g., ci.yourcompany.com) to secure the instance with HTTPS.
  4. An OAuth application created on your preferred Git platform (e.g., GitHub or Gitea) to handle user authentication.
Security Note: Always ensure your VPS firewall (e.g., UFW) is active, exposing only ports 80, 443, and necessary SSH ports to the public internet.

Step-by-Step Guide: Deploying Woodpecker CI with Docker Compose

Using Docker Compose allows us to define the Woodpecker server, agent, and a reverse proxy (like Nginx or Traefik) in a single, easily manageable configuration file.

Step 1: Setting up OAuth Apps

To allow users to log in, you must register Woodpecker with your Git provider. For GitHub, navigate to Developer Settings > OAuth Apps > New OAuth App. Set the Homepage URL to your domain ([https://ci.yourcompany.com](https://ci.yourcompany.com)) and the Authorization callback URL to [https://ci.yourcompany.com/login](https://ci.yourcompany.com/login). Safely record the generated Client ID and Client Secret.

Step 2: Creating the Configuration Files

Connect to your VPS via SSH and create a dedicated directory for your CI system:

mkdir -p ~/woodpecker-ci && cd ~/woodpecker-ci

Create a docker-compose.yml file with the following structural layout:

version: '3.8'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    volumes:
      - woodpecker-server-data:/var/lib/woodpecker
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=[https://ci.yourcompany.com](https://ci.yourcompany.com)
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=your_client_id_here
      - WOODPECKER_GITHUB_SECRET=your_client_secret_here
      - WOODPECKER_AGENT_SECRET=a_long_random_secret_string
    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=a_long_random_secret_string
    restart: always
    depends_on:
      - woodpecker-server

volumes:
  woodpecker-server-data:

Make sure to replace your_client_id_here, your_client_secret_here, and a_long_random_secret_string with your actual credentials and a securely generated token.

Step 3: Launching the Infrastructure

Execute the following command to pull the images and launch the containers in detached mode:

docker compose up -d

Verify that both containers are running optimally by executing docker compose ps.

Writing Your First Woodpecker Pipeline

Configuration in Woodpecker is strictly declarative. You define your build steps in a file named .woodpecker.yml placed at the root of your Git repository. Here is a practical example for a Node.js application:

pipeline:
  test:
    image: node:20
    commands:
      - npm install
      - npm run test

  build:
    image: node:20
    commands:
      - npm run build
    when:
      branch: main

  deploy:
    image: appleboy/drone-ssh
    settings:
      host: xvps.yourcompany.com
      username: deploy-user
      key: 
        from_secret: deploy_key
      script:
        - cd /var/www/app && git pull && pm2 restart app
    when:
      branch: main
      event: push

In this architecture, Woodpecker will automatically execute tests on every pull request. If the code is merged into the main branch, it triggers the build step and utilizes an SSH plugin container to securely deploy the code to production.

Best Practices for VPS CI/CD Management

Operating an automated CI/CD pipeline on a constrained server ecosystem requires adherence to strict architectural best practices:

1. Implement Aggressive Docker Pruning

Because Woodpecker instantiates Docker containers for every step, cached images and dangling volumes can quickly deplete your VPS storage. It is highly recommended to set up a daily Linux cron job running docker system prune -af --volumes to keep storage overhead to a minimum.

2. Leverage Secret Management

Never hardcode production passwords, API tokens, or private SSH keys into your .woodpecker.yml file. Always store them securely within the Woodpecker Web UI under the repository settings and reference them via the from_secret syntax.

3. Concurrency Limits

To prevent your VPS from grinding to a halt during intensive, simultaneous builds, limit agent execution capacity. You can configure the WOODPECKER_MAX_WORKERS environment variable on your agent container to cap concurrent builds based on your server's CPU core availability.

Conclusion

Transitioning to Woodpecker CI enables organizations and solo developers to maintain enterprise-grade DevOps workflows without incurring steep cloud infrastructure costs. Its lightweight nature, modular agent-server model, and deep container native execution environment make it the ideal pairing for standard VPS hosting. By following this guide, you have established a foundational platform that ensures rapid, automated, and secure software delivery cycles.

Deploying Woodpecker CI on a VPS: A Lightweight, Docker-Powered Continuous Integration System | DPTCloud