
Most CI setups fail in predictable ways. Hosted bills climb as you add parallel jobs. You end up on runners you don’t control. Build logs and artifacts live on someone else’s infrastructure.
If you already host code in Gitea or Forgejo, you can run Woodpecker CI on a VPS. That keeps the full loop—repos, pipelines, artifacts, and secrets—on machines you own.
This is a practical spotlight on Woodpecker CI. You’ll see who it’s for, what it replaces, and how to deploy it with Docker Compose. It also covers HTTPS, backups, and low-drama updates.
Why Woodpecker CI pairs well with Gitea and Forgejo
Woodpecker CI is an open-source, self-hosted CI system built around “pipeline as code.” You commit a .woodpecker.yml file to the repo. Woodpecker reads it and runs each step on your runners.
The architecture is simple by design. You run a server (web UI + API) and one or more agents. Agents execute steps as containers.
For Gitea/Forgejo shops, the fit is straightforward. OAuth, webhooks, and repo metadata stay inside your environment. That cuts down on external dependencies and moving parts.
Debugging gets boring again—in the best way.
- Best for: small-to-mid teams, agencies, and solo devs who want predictable CI costs and full control over build environments.
- Not ideal for: huge monorepos that need enterprise workflow features, or workloads that rely on proprietary hosted caches and massive ephemeral runner fleets.
License note: Woodpecker CI is open source (Apache-2.0). Gitea is open source (MIT). Forgejo is open source (commonly used under a GPL family license). Confirm the license for your specific fork/build and match it to your compliance needs.
What “run Woodpecker CI on a VPS” replaces (and what you give up)
The real choice is usually hosted CI (GitHub Actions, GitLab SaaS CI, CircleCI) versus running CI on your own server.
Self-hosting tends to win when builds are steady and you care about locality. You can keep dependencies close to the runner. You can use a private registry without odd egress rules. You can store artifacts on the same box (or at least the same network).
Self-hosting also helps when you need Docker-in-Docker or privileged steps. SaaS policies often block those.
- You gain: fixed infrastructure cost, control over runner images, local network access to staging services, and build logs that stay on your server.
- You give up: instant “infinite” scaling, vendor-managed patching, and some integrations that are deepest in GitHub/GitLab ecosystems.
If you want a baseline for what the Gitea side should look like first, HostMyCode already has a solid deployment guide for the repo host: Deploy Gitea on a VPS With SSH Git and HTTPS.
Infrastructure sizing: what your VPS needs for Woodpecker
Woodpecker itself is light. The runners are what consume resources.
Size the VPS around what you build (Node installs, Go builds, Docker images, test databases) and how much parallelism you expect.
- Small (personal / 1–2 repos): 1 vCPU, 2 GB RAM, 40+ GB NVMe. Fine for basic lint/test pipelines.
- Team (several repos): 2–4 vCPU, 4–8 GB RAM, 80+ GB NVMe. Comfortable for parallel builds and image builds.
- Busy CI (frequent builds, big images): 4–8 vCPU, 8–16 GB RAM, 160+ GB NVMe, and consider separating runner nodes.
Don’t ignore disk I/O. Docker layer extraction and dependency installs punish slow storage.
If builds feel “randomly slow,” check disk throughput before rewriting your pipeline.
If you want the straightforward route, a HostMyCode VPS gives you predictable resources and root access, which runners typically need.
If you’d rather not babysit OS updates and security baselines, managed VPS hosting fits CI boxes well because they must stay patched.
How the pieces fit: server, agent, and Gitea OAuth
Before you paste a Compose file, be clear on what talks to what.
- Woodpecker server: web UI + API; stores settings, repo list, pipeline status; receives webhooks from Gitea/Forgejo.
- Woodpecker agent: executes pipelines. In the common Docker setup, each pipeline step runs in its own container.
- Gitea/Forgejo OAuth app: lets Woodpecker authenticate users and access repos.
Treat the CI server like any production service. Put it behind a reverse proxy, terminate TLS, back up its persistent state, and keep logs.
If you already run Nginx for other apps, reuse the same pattern.
Deploy Woodpecker + agents with Docker Compose
This section is opinionated, but the configs are real. A stable pattern for most VPS installs is one Compose stack with persistent volumes. Then add an Nginx reverse proxy on the host.
Host assumptions: Ubuntu 24.04 LTS or Debian 12/13 on a VPS, Docker Engine + Compose plugin installed, and a DNS record pointing ci.yourdomain.com to the VPS.
Create the OAuth app in Gitea/Forgejo
In your Gitea/Forgejo UI:
- Go to Settings → Applications → Manage OAuth2 Applications.
- Create a new OAuth2 app with a callback like:
https://ci.yourdomain.com/authorize - Copy the Client ID and Client Secret.
Also create (or pick) a shared secret for webhooks. You’ll use it as Woodpecker’s webhook/agent secret and in your Gitea integration.
Compose file you can actually maintain
Create a working directory:
sudo mkdir -p /opt/woodpecker
cd /opt/woodpecker
Then create /opt/woodpecker/docker-compose.yml:
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
container_name: woodpecker-server
restart: unless-stopped
environment:
# Public URL of your Woodpecker instance
WOODPECKER_HOST: "https://ci.yourdomain.com"
# Gitea / Forgejo integration
WOODPECKER_GITEA: "true"
WOODPECKER_GITEA_URL: "https://git.yourdomain.com"
WOODPECKER_GITEA_CLIENT: "YOUR_GITEA_OAUTH_CLIENT_ID"
WOODPECKER_GITEA_SECRET: "YOUR_GITEA_OAUTH_CLIENT_SECRET"
# Webhook secret shared with Gitea/Forgejo
WOODPECKER_AGENT_SECRET: "GENERATE_A_LONG_RANDOM_SECRET"
# First user auto-admin (set to your Gitea username)
WOODPECKER_ADMIN: "your-gitea-username"
# Optional: restrict who can sign in
# WOODPECKER_ORGS: "your-org"
volumes:
- woodpecker-data:/var/lib/woodpecker
ports:
- "127.0.0.1:8000:8000"
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
container_name: woodpecker-agent
restart: unless-stopped
depends_on:
- woodpecker-server
environment:
WOODPECKER_SERVER: "http://woodpecker-server:8000"
WOODPECKER_AGENT_SECRET: "GENERATE_A_LONG_RANDOM_SECRET"
WOODPECKER_MAX_PROCS: "2"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
volumes:
woodpecker-data:
A few practical notes before you hit deploy:
127.0.0.1:8000keeps the Woodpecker server private to the VPS. Only Nginx should be exposed publicly.- The agent mounts the Docker socket. That’s common and convenient, but it’s also a lot of power. Treat this as a CI host. Keep it patched, and restrict who can enable repos and change pipeline YAML.
WOODPECKER_MAX_PROCScontrols parallel pipeline execution per agent. Start low. CI can chew through CPU quickly.
Start it:
sudo docker compose up -d
sudo docker compose ps
Reverse proxy with HTTPS (Nginx + Let’s Encrypt)
Put CI behind TLS on a real hostname. That prevents OAuth callback mismatches. It also avoids mixed-content issues later.
If you prefer Caddy, that works too. HostMyCode has a helpful reference for TLS automation and DNS patterns: Set Up Let’s Encrypt With Caddy for a VPS Site. Here we’ll use Nginx since it’s still the default on a lot of VPS fleets.
Nginx site config
Create /etc/nginx/sites-available/woodpecker:
server {
listen 80;
server_name ci.yourdomain.com;
location /.well-known/acme-challenge/ {
root /var/www/html;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl http2;
server_name ci.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/ci.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ci.yourdomain.com/privkey.pem;
# Keep headers boring and safe
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
location / {
proxy_pass http://127.0.0.1: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;
}
}
Enable it and reload Nginx:
sudo ln -s /etc/nginx/sites-available/woodpecker /etc/nginx/sites-enabled/woodpecker
sudo nginx -t
sudo systemctl reload nginx
Issue the certificate
Using Certbot (Ubuntu/Debian packages):
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ci.yourdomain.com
Afterward, re-check the generated Nginx config. Certbot may edit it, and you’ll want it to stay readable.
First-run checks: make sure CI actually triggers
The first failure is often plumbing, not YAML.
- Webhook delivery: in Gitea/Forgejo, check the webhook delivery log. You should see 2xx responses.
- Server reachability: the CI URL must be reachable from Gitea/Forgejo. If both are on the same VPS, this is simple. If they’re on separate hosts, open ports deliberately.
- Agent connected: in the Woodpecker UI, confirm at least one agent is online. If none appear, the agent secret or server URL is wrong.
If you want extra access controls around admin surfaces, a tunnel can help. This guide is useful even if you don’t apply it directly to CI: Set Up Cloudflare Tunnel on a VPS for Private Admin.
Backups you can restore: volumes, config, and secrets
CI stops being “stateless” once you care about audit trails or reproducibility.
If a disk dies or an update goes sideways, you want job history, repo config, and secrets back quickly.
At minimum, back up:
- Woodpecker data volume:
woodpecker-data(contains the server state database). - Compose files:
/opt/woodpecker/docker-compose.ymland any.envyou use. - Nginx config:
/etc/nginx/sites-available/woodpecker. - Let’s Encrypt:
/etc/letsencrypt(optional, but it saves time).
A simple volume backup command
This pattern avoids a long outage. On a tiny instance, a brief stop is fine. On a busier CI box, run it during off-hours.
# Optional: stop to get a clean snapshot
cd /opt/woodpecker
sudo docker compose stop woodpecker-server
# Backup the named volume to a timestamped tarball
BACKUP_DIR=/var/backups/woodpecker
sudo mkdir -p "$BACKUP_DIR"
sudo docker run --rm \
-v woodpecker_woodpecker-data:/data:ro \
-v "$BACKUP_DIR":/backup \
alpine sh -c "cd /data && tar -czf /backup/woodpecker-data-$(date +%F).tar.gz ."
# Start again
sudo docker compose start woodpecker-server
Do a restore test. If you’ve never restored it, it’s not a backup—it’s a hopeful archive.
If you run other services on the same VPS (MariaDB, Postgres, etc.), keep the same discipline. HostMyCode’s restore-tested approach is worth copying even outside MySQL: Set Up Automatic MySQL Backups With Tested Restores.
Updating Woodpecker safely (without breaking pipelines)
Updates are usually straightforward. Still, it pays to follow the same routine every time.
- Back up the data volume and Compose file.
- Pull new images.
- Restart the stack.
- Verify agent connectivity and run a small pipeline.
cd /opt/woodpecker
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune -f
If you need strict change control, pin image tags instead of using :latest. That does mean tracking releases yourself.
For most small operators, a monthly maintenance window is enough.
Common operational pitfalls (and how to avoid them)
These issues tend to show up after the first few weeks.
- Runner saturation: builds queue up and “CI is slow” becomes the default complaint. Add CPU/RAM, run another agent container, or lower parallelism.
- Disk fills up: Docker images, caches, and artifacts keep growing. Watch
/var/lib/dockerand prune images on a schedule. - Insecure pipelines: if untrusted users can push YAML to a repo, they can run code on your runner. Limit who can enable repos in Woodpecker and handle secrets with care.
- OAuth callback mismatch:
WOODPECKER_HOSTand the OAuth callback must match exactly, includinghttps.
If you want visibility beyond “the build failed,” ship host/container metrics into dashboards. This HostMyCode Grafana guide is a good starting point for CPU, disk, and container health: Deploy Grafana on a VPS With Docker, TLS, and Backups.
Where Woodpecker fits in a real hosting stack
Most teams start with Gitea and Woodpecker on the same VPS. That’s fine early on.
The pain shows up when builds compete with your Git service for CPU and disk I/O. Busy build windows can make Git feel sluggish.
A sensible growth path looks like this:
- Phase 1: Gitea + Woodpecker server + 1 agent on one VPS.
- Phase 2: move agents to a second VPS so build spikes don’t drag Git performance down.
- Phase 3: dedicated server for CI runners if you build large Docker images all day or compile heavy workloads.
HostMyCode makes that progression straightforward: start with a HostMyCode VPS, then add capacity or split roles.
If you need stronger isolation and consistent throughput for runners, a dedicated machine is often cheaper than oversizing a general VPS for months.
If you’re planning to run your own CI, keep it on infrastructure you can control and recover quickly. A HostMyCode VPS gives you the permissions runners need, while managed VPS hosting is a good fit if you want OS patching and core hardening handled for you.
FAQ
Should I run Woodpecker on the same VPS as Gitea?
For small teams, yes. Once your builds start compiling large projects or building container images frequently, split runners to another VPS so Git stays responsive.
Do I need a database container for Woodpecker?
In the common setup, Woodpecker stores its state in its own internal data directory. Back up the /var/lib/woodpecker volume and you’re covering the important state.
Is mounting /var/run/docker.sock safe?
It’s a standard pattern for Docker-based CI, but it grants powerful access. Only enable trusted repos, restrict who can change pipeline YAML, and keep the CI host patched.
How do I add more runners?
Either scale the agent container on the same host (and raise CPU/RAM), or add a second VPS and run additional agents there pointing at the same Woodpecker server.
What’s the minimum I should back up?
Back up the Woodpecker data volume, your Compose configuration, and your reverse proxy/TLS configuration. Then do a restore test so you know it boots cleanly.
Summary
Woodpecker CI makes sense if you already run Gitea/Forgejo and want predictable pipelines without SaaS pricing surprises.
Put the server behind HTTPS, keep runner capacity under control, back up the data volume, and handle updates like any other production change.
If you want a stable place to run Woodpecker CI on a VPS, start with a HostMyCode VPS and split runners out as build load grows. HostMyCode’s focus on Affordable & Reliable Hosting keeps that step-up path predictable.