Woodpecker CI on Uberspace

In an effort to migrate away from BigTech™ and US-based services, I came accross Woodpecker CI as a CI/CD platform. This guide should help you install and configure it. We’ll be using Codeberg as our ForgeJo platform, which has built-in support for Woodpecker CI.

Uberspace as a platform

For people who don’t know Uberspace: it’s a German hosting provider that provides easy access to maintained VPS servers with access to preconfigured services. All configs are done through SSH. It’s a good middleground between a managed server and a standard VPS.

Installing & Configuring Woodpecker CI

I loosely based it on the install processes of other services on Uberspace. So log in to your Uberspace server via SSH and follow these steps.

1. Download and unpack Woodpecker CI

Go to the Woodpecker Releases Page and find the latest version. Copy the links for the server and agent amd64 compressed binaries and download them to your Uberspace server, e.g. in ~/apps/woodpecker.

# Create app directory
mkdir woodpecker
cd woodpecker
# Download server and agent. Be sure to replace the Version
wget https://github.com/woodpecker-ci/woodpecker/releases/download/v3.12.0/woodpecker-server_linux_amd64.tar.gz
wget https://github.com/woodpecker-ci/woodpecker/releases/download/v3.12.0/woodpecker-agent_linux_amd64.tar.gz
# Unpack them
tar -xvzf woodpecker-server_linux_amd64.tar.gz
tar -xvzf woodpecker-agent_linux_amd64.tar.gz

You should now have two binaries: woodpecker-server and woodpecker-agent.

2. Get the Codeberg OAuth credentials

We’ll need a Codeberg OAuth Client id an secret with a configured redirect URL in order to authenticate and find our repositories.

To create the token, go to your account settings. At the botton, you can create an OAuth2 application. Give it a good name. For redirect URL, use: {YOUR_DOMAIN}/authorize. Copy the Client ID and Client Secret somewhere safe, we’ll need them later.

On your uberspace, create the subdomain and be sure to update your DNS.

3. Configure Woodpecker CI and your supervisor services

First up, we’ll need .env files for our server & agent.

# Create an agent secret and copy it
openssl rand -base64 32

# Create and edit the server env file
vim woodpecker-server.env
# Paste and configure the following content
WOODPECKER_HOST=https://{your_domain}
WOODPECKER_OPEN=true
WOODPECKER_FORGEJO=true
WOODPECKER_FORGEJO_URL=https://codeberg.org
WOODPECKER_SERVER_ADDR={your_port}
WOODPECKER_FORGEJO_CLIENT={codeberg_client_id}
WOODPECKER_FORGEJO_SECRET={codeberg_client_secret}
WOODPECKER_AGENT_SECRET={above_generated_agent_secret}
# Optional, helped me debugging
WOODPECKER_LOG_FILE=$HOME/woodpecker/server.logs
# Save and exit :)
:wq

# Create and edit the agent env file
vim woodpecker-agent.env
# Paste and configure the following content
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET={above_generated_agent_secret}
WOODPECKER_MAX_WORKFLOWS=8
# Save and exit :)
:wq

Since supervisor does not directly support env files, I created wrapper scripts for both server and agent. They just load the .env file and start the binary.

vim woodpecker-server-start.sh

#!/bin/bash
set -a  # auto-export
source "$HOME/woodpecker/woodpecker-server.env"
set +a
exec "$HOME/woodpecker/woodpecker-server"

# Save and exit :)
:wq

Repeat for the agent and replace woodpecker-server with woodpecker-agent.

Now we can create the supervisor service files.

vim ~/etc/services.d/woodpecker-server.ini

# Paste the following content
[program:woodpecker-server]
command=%(ENV_HOME)s/woodpecker/start-server.sh
directory=%(ENV_HOME)s/woodpecker
autostart=true
autorestart=unexpected
startsecs=1
stdout_logfile=AUTO
stderr_logfile=AUTO

# Save and exit :)
:wq

vim ~/etc/services.d/woodpecker-agent.ini

# Paste the following content
[program:woodpecker-agent]
command=%(ENV_HOME)s/woodpecker/start-agent.sh
directory=%(ENV_HOME)s/woodpecker
autostart=true
autorestart=unexpected
startsecs=1
stdout_logfile=AUTO
stderr_logfile=AUTO

# Save and exit :)
:wq

We are now ready to start the services.

supervisorctl reread
supervisorctl update

Now the services should start just fine. Be sure to expose the server port in your Uberspace web interface.

uberspace web backend set {your_domain}/ --http --port {your_port}

That’s it! Now everything should be running smoothly and be accessible via your domain. You should also be able to log in via Codeberg OAuth and see your repositories.