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.

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
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
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.

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.

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.