Woodpecker CI on a VPS: installation, configuration, and maintenance

Installing and configuring Woodpecker CI on a VPS allows you to deploy a powerful self-hosted CI/CD platform for automating the build, testing, and deployment of your code, utilizing Docker and Docker Compose for easy management and scaling.

In the modern software development cycle, Continuous Integration and Continuous Delivery (CI/CD) have become cornerstones of efficiency and reliability. Woodpecker CI is a lightweight yet powerful alternative to larger CI/CD systems, perfectly suited for deployment on your own server. In this article, we will detail how to install Woodpecker CI on a VPS, configure it to work with HTTPS, and ensure reliable service.

What is Woodpecker CI and why deploy it on a VPS?

Woodpecker CI is an open-source continuous integration platform developed as a fork of Drone CI. It provides a simple and efficient way to automate software build, testing, and deployment processes. Woodpecker CI is focused on working with Docker containers, making it a flexible and easily scalable solution.

Why is CI/CD needed?

CI/CD automates the development lifecycle, allowing teams to deliver changes faster and more reliably. Continuous Integration means developers frequently integrate their code into a shared branch, and automated tests run with every change, identifying issues early. Continuous Delivery extends this process by automatically preparing validated code for deployment, and Continuous Deployment takes it further by automatically rolling out to production. Woodpecker CI provides all the necessary infrastructure to implement these principles.

Advantages of Woodpecker CI Self-Hosted

Deploying Woodpecker CI on your own server, or as we say, Woodpecker CI self-hosted, gives you full control over data, security, and configuration. Unlike cloud services, you are not limited by their pricing plans or policies. Your own VPS from Valebyte.com provides dedicated resources, high performance, and configuration flexibility, which is critical for CI/CD systems that can consume significant resources during build execution. Using Woodpecker CI Docker images simplifies the deployment and management process, isolating the build environment and ensuring reproducible results.

By choosing Woodpecker CI on a server, you get:

• Full Control: Manage all aspects of the CI/CD process, from infrastructure to security policies.
• Flexibility: Customize the build environment to meet any, even the most specific, requirements of your projects.
• Confidentiality: Your source code and artifacts remain exclusively on your server.
• Cost Savings: In the long run, your own VPS can be more cost-effective than subscribing to expensive cloud CI/CD services, especially with a large volume of builds or many projects.
• Performance: Dedicated VPS resources guarantee predictable performance without "noisy neighbors."

System Requirements for Woodpecker CI on a Server

Before proceeding with the Woodpecker CI installation, it's important to ensure your VPS meets the minimum system requirements. Woodpecker CI consists of two main components: Server (Woodpecker CI server) and Agent (Woodpecker CI agent). The server manages pipelines, interacts with version control systems (Git, GitHub, GitLab, Gitea), and stores configuration. The agent performs actual build and testing tasks within Docker containers.

Minimum Configuration for Woodpecker CI

For small projects or individual use, where parallel builds or very resource-intensive tasks are not expected, the following minimum requirements are suitable:

• Operating System: Ubuntu 20.04+, Debian 11+, CentOS 8+, AlmaLinux 8+, Rocky Linux 8+. It is advisable to use a recent LTS version of Linux.
• Processor: 1 vCPU (e.g., Intel Xeon E3/E5 or AMD EPYC).
• RAM: 1 GB RAM.
• Disk Space: 10-20 GB NVMe SSD. NVMe drives significantly speed up I/O operations, which is important for Docker and builds.
• Network Connection: Stable internet connection with a public IP address.
• Docker: Installed and running Docker Engine.

This configuration will allow you to run the Woodpecker CI server and one or two agents for sequential builds. However, with active use, it will quickly become a bottleneck.

Recommendations for Production and Real-World Woodpecker CI Workloads

For development teams, multiple projects, parallel builds, and more intensive use where speed and stability are critical, the following configuration is recommended:

• Processor: 2-4 vCPU. The more cores, the more parallel Docker agents can be run.
• RAM: 4-8 GB RAM. This will allocate enough memory for both the Woodpecker CI server and several concurrently running build containers.
• Disk Space: 50-100 GB NVMe SSD. Keep in mind that Docker images and build artifacts can take up significant space.
• Database: For production, it is recommended to use an external database (PostgreSQL or MySQL) instead of the built-in SQLite. This increases reliability and performance. On a VPS, it can be deployed in a separate Docker container or use a managed service.
• Network Connection: 100 Mbps or 1 Gbps channel.

The choice of an optimal VPS for Woodpecker CI VPS depends on the number of developers, project complexity, and build frequency. It's always better to have a small resource buffer to avoid slowdowns during peak times.

Preparing the VPS for Woodpecker CI Docker Installation

Before proceeding with Woodpecker CI deployment, you need to prepare your VPS. This stage includes selecting the operating system, basic security configuration, and Docker installation.

Choosing an Operating System

For Woodpecker CI on a server, it is recommended to use stable and popular Linux distributions. The most common and well-supported options are:

• Ubuntu Server LTS (e.g., 22.04 LTS): An excellent choice for beginners and experienced users, with a large community and up-to-date packages.
• Debian Stable (e.g., 12 Bookworm): Known for its stability and security, but may have slightly older versions of some packages.
• AlmaLinux/Rocky Linux (CentOS analogs): Suitable for those accustomed to the Red Hat ecosystem.

After deploying the VPS, ensure the system is updated to the latest package versions:

sudo apt update && sudo apt upgrade -y

Or for RHEL-like systems:

sudo yum update -y

It is also recommended to configure a firewall (UFW for Debian/Ubuntu or firewalld for RHEL-like systems), allowing incoming connections only for SSH (port 22), HTTP (port 80), and HTTPS (port 443).

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

Installing Docker and Docker Compose

Woodpecker CI actively uses Docker, so its Woodpecker CI Docker installation is a mandatory step. Docker Compose simplifies the management of multi-container applications.

Step 1: Install Docker Engine

Follow the official Docker documentation for installation on your OS. For Ubuntu, it will look like this:

sudo apt update
sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Add your user to the docker group to avoid using sudo with every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Verify that Docker is installed and running:

docker run hello-world

Step 2: Install Docker Compose

Docker Compose is usually installed along with Docker Engine (as a docker compose plugin). If you have an older Docker version or it's not installed, you can install it separately. Check the version:

docker compose version

If the command doesn't work or the version is outdated, install it:

sudo apt install docker-compose -y

Or, for a newer version, download the binary:

sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose # For compatibility
docker-compose --version

Now your VPS is ready for Woodpecker CI deployment.

Step-by-Step Woodpecker CI Installation on VPS with Docker Compose

Now that your VPS is prepared, you can proceed with the actual Woodpecker CI installation. We will use Docker Compose for convenient management of the server and agent.

Step 1: Create the docker-compose.yml file

Create a directory for Woodpecker CI and inside it, a docker-compose.yml file:

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

Insert the following configuration. This is a basic example that uses SQLite for data storage (for simplicity) and runs one Woodpecker CI agent. Replace your.woodpecker.domain with your domain name and generate a secret key.

version: '3.8'

services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    restart: always
    ports:
      - "8000:8000" # Port for accessing the Woodpecker CI web interface
    volumes:
      - ./woodpecker-data:/var/lib/woodpecker # For storing SQLite data and configuration
    environment:
      WOODPECKER_HOST: https://your.woodpecker.domain # Your domain name
      WOODPECKER_RPC_SECRET: your_rpc_secret_key # Very important secret key
      WOODPECKER_ADMIN: your_admin_username # The username that will be the administrator
      WOODPECKER_OPEN: "true" # Allow new user registration (false for a closed system)
      WOODPECKER_GITLAB: "true" # Enable GitLab integration
      WOODPECKER_GITLAB_URL: https://gitlab.com # URL of your GitLab instance
      WOODPECKER_GITLAB_CLIENT: your_gitlab_client_id # GitLab OAuth application ID
      WOODPECKER_GITLAB_SECRET: your_gitlab_client_secret # GitLab OAuth application secret
      # WOODPECKER_GITHUB: "true" # For GitHub
      # WOODPECKER_GITHUB_CLIENT: your_github_client_id
      # WOODPECKER_GITHUB_SECRET: your_github_client_secret
      # WOODPECKER_GITHUB_SCOPE: repo,repo:status,user:email,read:org
      # WOODPECKER_GITEA: "true" # For Gitea
      # WOODPECKER_GITEA_URL: https://gitea.com
      # WOODPECKER_GITEA_CLIENT: your_gitea_client_id
      # WOODPECKER_GITEA_SECRET: your_gitea_client_secret
      # WOODPECKER_DATABASE_DRIVER: postgres # For using PostgreSQL
      # WOODPECKER_DATABASE_DATASOURCE: postgres://user:password@db:5432/woodpecker?sslmode=disable

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Give the agent access to the Docker daemon
    environment:
      WOODPECKER_SERVER: woodpecker-server:9000 # Server service name and RPC port
      WOODPECKER_RPC_SECRET: your_rpc_secret_key # The same secret key as for the server
      WOODPECKER_AGENT_LABELS: linux/amd64,default # Labels for the agent
      WOODPECKER_LOG_LEVEL: info
    depends_on:
      - woodpecker-server
    privileged: true # Required for running Docker-in-Docker or other privileged operations

Important configuration points:

• WOODPECKER_HOST: Specify the full domain name where Woodpecker CI will be accessible. This is critical for correct OAuth and webhook operation.
• WOODPECKER_RPC_SECRET: Generate a strong random secret (e.g., using openssl rand -hex 16 or an online generator). This secret is used for agent authentication with the server.
• WOODPECKER_ADMIN: Specify the username that will be automatically assigned as administrator after the first registration.
• Git Integration: Uncomment and fill in the variables for your version control system (GitHub, GitLab, Gitea). You will need to register a new OAuth application in your Git system (e.g., GitHub Settings -> Developer settings -> OAuth Apps) and specify the Redirect URL (Callback URL) in the format https://your.woodpecker.domain/authorize.
• Database: By default, SQLite is used, which is suitable for getting started. For production, consider PostgreSQL or MySQL. If you use PostgreSQL, add the corresponding service to docker-compose.yml and uncomment the WOODPECKER_DATABASE_DRIVER and WOODPECKER_DATABASE_DATASOURCE variables. An example of integration with NocoDB on VPS or Baserow on VPS can provide insight into working with databases in Docker, although Woodpecker uses them directly.
• privileged: true: The Woodpecker CI agent often requires privileged access to the Docker daemon to perform builds, especially if you are using Docker-in-Docker or other specific tools.

Step 2: Start Woodpecker CI

After saving the docker-compose.yml file, start the containers:

docker compose up -d

The -d command means running in detached mode. Check the status of the containers:

docker compose ps

You should see that both containers (woodpecker-server and woodpecker-agent) are running.

At this stage, Woodpecker CI will be accessible at http://your_vps_ip:8000. However, for production and correct operation with Git providers, it is essential to configure a reverse proxy with HTTPS.

Configuring Reverse Proxy (Nginx/Caddy) and HTTPS for Woodpecker CI

To ensure security and correct operation of Woodpecker CI with external services (such as GitHub/GitLab OAuth), it is necessary to configure a reverse proxy with HTTPS support. We will consider two popular options: Nginx and Caddy.

Nginx as Reverse Proxy for Woodpecker CI

Nginx is a high-performance web server and reverse proxy. If it is already installed on your VPS, configuring it will be simple.

Step 1: Install Nginx

If Nginx is not installed:

sudo apt update
sudo apt install nginx -y

Start Nginx and add it to autostart:

sudo systemctl start nginx
sudo systemctl enable nginx

Step 2: Configure Nginx

Create a new configuration file for your domain (e.g., /etc/nginx/sites-available/woodpecker.conf):

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

Insert the following configuration, replacing your.woodpecker.domain with your domain name:

server {
    listen 80;
    server_name your.woodpecker.domain;

    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 900s; # Increase timeout for long builds
    }
}

Create a symbolic link to this file in sites-enabled:

sudo ln -s /etc/nginx/sites-available/woodpecker.conf /etc/nginx/sites-enabled/

Test the Nginx configuration and reload it:

sudo nginx -t
sudo systemctl reload nginx

Now Woodpecker CI should be accessible via HTTP at your domain name.

Step 3: Configure HTTPS with Let's Encrypt (Certbot)

For HTTPS, we use Certbot from Let's Encrypt. Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

Run Certbot to automatically configure Nginx and obtain a certificate:

sudo certbot --nginx -d your.woodpecker.domain

Certbot will ask a few questions (email, agreement to terms). After successful execution, it will automatically update the Nginx configuration, adding HTTPS and redirecting from HTTP to HTTPS. Check your site at https://your.woodpecker.domain.

Caddy as Reverse Proxy for Woodpecker CI

Caddy is a modern web server with automatic HTTPS support (Let's Encrypt). It is easy to configure and ideal for such tasks.

Step 1: Install Caddy

Follow the official Caddy documentation for installation. For Debian/Ubuntu:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Step 2: Configure Caddyfile

Create or edit the /etc/caddy/Caddyfile file:

sudo nano /etc/caddy/Caddyfile

Remove existing content and insert the following, replacing your.woodpecker.domain with your domain name:

your.woodpecker.domain {
    reverse_proxy localhost:8000 {
        header_up X-Forwarded-Proto {scheme}
        header_up X-Real-IP {remote_ip}
        header_up Host {host}
    }
    # Increase timeout for long builds, if necessary
    # transport http {
    #     read_timeout 15m
    # }
}

Caddy will automatically obtain and renew Let's Encrypt certificates for your domain.

Step 3: Start Caddy

Validate the Caddy configuration and restart it:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Now Woodpecker CI should be accessible via HTTPS at your domain name. Go to https://your.woodpecker.domain, register (if WOODPECKER_OPEN is set to true), and start integrating with your Git repositories.

At this stage, Woodpecker CI installation is complete, and the system is ready for use.

Backups and Updates of Woodpecker CI

Regular backups and timely updates are critically important for the stable and secure operation of any self-hosted system, including Woodpecker CI on a server.

Woodpecker CI Backup Strategy

Woodpecker CI stores its data in the directory we mounted as a volume: ./woodpecker-data. For the built-in SQLite database, this will be the woodpecker.sqlite file. If you are using an external database (PostgreSQL/MySQL), you will also need to ensure it is backed up. Additionally, it is important to save Docker Compose configuration files.

What needs to be backed up:

1. Woodpecker CI data directory (~/woodpecker-ci/woodpecker-data/).
2. The docker-compose.yml file.
3. Reverse proxy configurations (Nginx: /etc/nginx/sites-available/woodpecker.conf; Caddy: /etc/caddy/Caddyfile).
4. SSL/TLS certificates (although Certbot can restore them).

Example backup script:

Create a script backup_woodpecker.sh:

#!/bin/bash

BACKUP_DIR="/var/backups/woodpecker_ci"
TIMESTAMP=$(date +%Y%m%d%H%M%S)
WOODPECKER_ROOT_DIR="/root/woodpecker-ci" # Or your path

mkdir -p $BACKUP_DIR/$TIMESTAMP

echo "Creating Woodpecker CI data backup..."
cp -R $WOODPECKER_ROOT_DIR/woodpecker-data $BACKUP_DIR/$TIMESTAMP/
cp $WOODPECKER_ROOT_DIR/docker-compose.yml $BACKUP_DIR/$TIMESTAMP/

# If using Nginx
# cp /etc/nginx/sites-available/woodpecker.conf $BACKUP_DIR/$TIMESTAMP/
# cp -R /etc/letsencrypt/live/your.woodpecker.domain $BACKUP_DIR/$TIMESTAMP/certs/

# If using Caddy
# cp /etc/caddy/Caddyfile $BACKUP_DIR/$TIMESTAMP/
# cp -R /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/your.woodpecker.domain $BACKUP_DIR/$TIMESTAMP/certs/

# If using PostgreSQL
# docker exec your_postgres_container_name pg_dump -U your_postgres_user your_postgres_db > $BACKUP_DIR/$TIMESTAMP/woodpecker_postgres_dump.sql

echo "Compressing backup..."
tar -czvf $BACKUP_DIR/woodpecker_ci_backup_$TIMESTAMP.tar.gz -C $BACKUP_DIR $TIMESTAMP
rm -rf $BACKUP_DIR/$TIMESTAMP

echo "Backup completed: $BACKUP_DIR/woodpecker_ci_backup_$TIMESTAMP.tar.gz"

# Delete old backups (e.g., older than 7 days)
find $BACKUP_DIR -name "woodpecker_ci_backup_*.tar.gz" -mtime +7 -delete
echo "Old backups deleted."

Make the script executable and add it to Cron for daily execution:

chmod +x backup_woodpecker.sh
(crontab -l; echo "0 3 * * * /root/woodpecker-ci/backup_woodpecker.sh") | crontab -

Consider using external backup tools, such as Restic, which we described in the article Restic on VPS: Installation, Configuration, and Maintenance. It allows you to securely and efficiently store encrypted backups on various remote storage options.

Woodpecker CI Update Process

Updating Woodpecker CI usually involves updating the Docker images for the server and agent.

1. Create a backup: Always perform a full backup before any update.
2. Stop containers:

cd ~/woodpecker-ci
docker compose down

3. Pull new images:

docker compose pull

4. Start containers with new images:

docker compose up -d

5. Check logs: Ensure everything started without errors.

docker compose logs -f

Regularly check the official Woodpecker CI GitHub repository for new releases and important configuration changes.

Which VPS configuration to choose for a real Woodpecker CI workload?

Choosing the optimal VPS for Woodpecker CI VPS is a balance between cost and performance. Overpaying for excessive resources is inefficient, but a lack of resources will lead to slower builds and reduced team productivity.

Load Assessment and Scaling

The load on Woodpecker CI is primarily determined by:

• Number of parallel builds: The more projects or branches are built simultaneously, the more resources are required.
• Resource intensity of builds: Compiling large C++/Java projects, running many tests, building Docker images – all require CPU, RAM, and a fast disk.
• Size of repositories and artifacts: Affects disk space and network bandwidth.
• Number of agents: Each Woodpecker CI agent is essentially a Docker host for builds. You can run multiple agents on one powerful VPS or distribute them across several servers.

Let's consider typical scenarios and recommended VPS configurations from Valebyte.com:

Usage Scenario	vCPU	RAM	NVMe SSD	Bandwidth	Approximate Cost (Valebyte.com)
Personal/Test (1-2 projects, 1-2 developers, infrequent builds)	2	2 GB	40 GB	100 Mbps	from $7-10/month
Small Team (3-5 projects, 3-7 developers, 2-3 parallel builds)	4	4 GB	80 GB	200 Mbps	from $15-20/month
Medium Team/Multiple Teams (5-15 projects, 8-20 developers, 4-8 parallel builds)	6-8	8-16 GB	160-320 GB	500 Mbps - 1 Gbps	from $30-60/month
Large Enterprise/High-Load CI (20+ projects, 20+ developers, 10+ parallel builds)	12-16+	32-64+ GB	500 GB+	1 Gbps+	from $80-150+/month (or dedicated server)

Recommended Valebyte.com Plans

For most users starting with Woodpecker CI on a VPS, we recommend starting with a plan that offers at least 4 vCPU, 4 GB RAM, and 80 GB NVMe SSD. This will ensure comfortable operation for a small to medium team, allowing several builds to run in parallel without significant delays.

If you manage other tools on your VPS, such as OpenProject on VPS, Redmine on VPS, or Filebrowser on VPS, be sure to consider their system requirements when choosing a plan. In such a case, a more powerful VPS may be required to ensure stable operation of all services.

The key factor is always disk subsystem performance. NVMe SSD drives, offered by Valebyte.com, are critically important for fast Docker container operation, repository retrieval, and dependency caching during the build process. High network bandwidth is also important for quickly downloading Docker images, dependencies, and uploading artifacts.

Monitoring your VPS resources (CPU, RAM, disk I/O) will help you understand when it's time to scale. If the CPU is consistently loaded at 80-90% during builds, or disk I/O becomes a bottleneck, it's a clear signal for an upgrade.

Conclusion

Woodpecker CI on a VPS from Valebyte.com offers a powerful, flexible, and cost-effective solution for automating CI/CD processes. By following the detailed installation instructions, configuring a reverse proxy with HTTPS, and implementing backup and update strategies, you can create a reliable and high-performance platform for your development team.