How to Self-Host Woodpecker CI on a VPS (Complete Guide)

How to Self-Host Woodpecker CI on a VPS (Complete Guide)

Woodpecker CI is an open-source Continuous Integration and Continuous Deployment (CI/CD) system. Self-hosting it can streamline your development pipeline while allowing you to control your environment. In this guide, we will walk you through the steps to install and configure Woodpecker CI on a VPS using Docker.

We run Woodpecker next to a Gitea instance and it has been the lowest maintenance CI we have used. Worth knowing before you start: the server and the agent are two separate pieces. The command below starts the server only, and it will sit there looking perfectly healthy and never run a build until an agent is connected to it.

Prerequisites

1. VPS: Select a VPS provider. Here’s a comparison of popular VPS options for hosting your Woodpecker CI:

Choose a provider that matches your requirements, taking into account performance and budget. For a detailed VPS comparison, check out the full VPS comparison.

2. Operating System: Ensure you’re using a suitable operating system, ideally Ubuntu 20.04 or later.

3. Docker: Install Docker on your VPS.

Step 1: Setting Up Docker

To install Docker on Ubuntu, run the following commands:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce

After installation, verify that Docker is running:

sudo systemctl start docker
sudo systemctl enable docker
sudo systemctl status docker

Step 2: Install Woodpecker CI

1. Pull the Woodpecker CI Docker Image:

   Use the following command to pull the Woodpecker CI image:

docker pull woodpeckerci/woodpecker

2. Create and Run the Woodpecker CI Container:

Now that you have the image, create a container. You will need to set various environment variables based on your configuration:

docker run -d \
  --name woodpecker \
  --volume /var/lib/woodpecker:/data \
  -e WOODPECKER_GITEA_SERVER=https://your-gitea-instance.com \
  -e WOODPECKER_RPC_SECRET=your-rpc-secret \
  -e WOODPECKER_SERVER=true \
  -p 8000:8000 \
  woodpeckerci/woodpecker

Adjust WOODPECKER_GITEA_SERVER and WOODPECKER_RPC_SECRET according to your Gitea instance or any other Git service you are using.

Two more things you will need in practice. WOODPECKER_HOST has to be the URL Gitea can actually reach, because that is what ends up written into the webhooks, and an agent has to be started with the same WOODPECKER_RPC_SECRET before anything builds. Set WOODPECKER_ADMIN to your own username on the first run too, otherwise you have no admin account and the simplest fix is starting over.

Step 3: Configure Woodpecker CI

1. Accessing the Web UI: Open your web browser and navigate to http://<your-vps-ip>:8000. You should see the Woodpecker CI interface.

2. Register Webhooks: If using Gitea, ensure you register webhooks to connect your repositories with Woodpecker CI for triggering builds.

3. Integrate with Other Services: Depending on your project needs, integrate notifications or deploy steps by editing .woodpecker.yml.

FAQs

1. What are the benefits of self-hosting Woodpecker CI over using a SaaS option?

Self-hosting Woodpecker CI provides complete control over your build environment, allowing you to customize configurations based on project requirements. You can avoid limitations imposed by third-party services, such as build time quotas and lack of access to source code logs. Moreover, self-hosting enhances privacy, as your code and data remain within your infrastructure.

2. Can I scale my Woodpecker CI instance based on traffic demands?

Yes, one of the major advantages of using Docker is scalability. If you notice peaks in CI/CD usage, you can adjust the number of Woodpecker CI instances or allocate additional resources to your VPS. Consider using containers orchestration tools like Kubernetes or Docker Compose to manage multiple instances and scale effectively.

3. How do backup and restore work when self-hosting Woodpecker CI?

Ensure regular backups of your Woodpecker CI data folder (/var/lib/woodpecker) to avoid data loss. Use your VPS provider’s backup solutions or script regular tar archiving of the Woodpecker data directory. In case of data corruption or loss, simply restore the backed-up data to the same directory, and restart the Woodpecker CI container.

One more thing worth doing on day one: keep builds off the machine that runs the server if you can. We started with both on a single VPS and one runaway build took the whole CI down with it. Moving agents onto a separate box, even a small one, is what made it dependable.

By following these steps, you should have a fully functional Woodpecker CI instance running on your VPS. This setup enables more efficient development processes, tailored to your unique requirements.