Skip to content

Self-host Woodpecker CI

updated Sep 2026prices checked · Jul 2026
We earn commissions when you shop through the links below. Full disclosure →

A lightweight CI/CD engine, forked from Drone, that runs pipelines defined in YAML as Docker containers. It has no user accounts of its own: you log in through a connected forge such as GitHub, Gitea, Forgejo or GitLab.

Key facts

CategoryCI/CD
LicenseApache-2.0
StackGo, Vue
Min RAM256 MB
Official imageyes
Difficulty

What you need

  • Any VPS with at least 256 MB of RAM
  • A domain you control — most self-hosted setups need HTTPS in front of them
  • Under an hour if you've used Docker before
Where to host itaffiliate disclosure
Hetzner Cloudrun it on
From $23.59/mo · 2 vCPU / 4 GB / 80 GB · EU + US
Get Hetzner Cloud (opens in new tab)
Kamaterafree trial
From $4/mo · 1 vCPU / 1 GB / 20 GB · US + EU + Asia
Start free on Kamatera → (opens in new tab)
DigitalOceanalso works on
From $6/mo · 1 vCPU / 1 GB / 25 GB · US + EU + Asia
Deploy on DigitalOcean → (opens in new tab)

Paid link — we earn a commission if you shop through it.

Install

Run these commands on your server:

# Woodpecker server + agent — official compose (GitHub forge); create a GitHub OAuth app first,
# callback URL http://SERVER_IP:8000/authorize, and paste its client id + secret below
mkdir -p ~/woodpecker && cd ~/woodpecker
cat > .env <<EOF
WOODPECKER_HOST=http://SERVER_IP:8000
WOODPECKER_GITHUB_CLIENT=your-github-oauth-client-id
WOODPECKER_GITHUB_SECRET=your-github-oauth-client-secret
WOODPECKER_AGENT_SECRET=$(openssl rand -hex 32)
EOF
cat > docker-compose.yml <<'EOF'
services:
  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v3
    ports: ["8000:8000"]
    volumes: ["woodpecker-server-data:/var/lib/woodpecker/"]
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITHUB=true
      - WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
      - WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v3
    command: agent
    restart: always
    depends_on: [woodpecker-server]
    volumes: ["woodpecker-agent-config:/etc/woodpecker", "/var/run/docker.sock:/var/run/docker.sock"]
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
volumes:
  woodpecker-server-data:
  woodpecker-agent-config:
EOF
docker compose up -d
# open http://SERVER_IP:8000 and log in with GitHub

More self-hosted tools

We use analytics cookies (Google Analytics, PostHog) to see which guides are useful. No ad networks, no cross-site tracking. See our privacy policy.