Git and CI, checked 2026-09-07
Woodpecker: Docker configuration reference
Self-hosted CI/CD engine that runs pipelines defined in YAML, split into a server and one or more agents.
At a glance
Ports
Ports| Port | What listens | Source |
|---|
8000 | HTTP listener for the web UI and API. Point the reverse proxy here. | source for port 8000 |
9000 | gRPC listener agents connect to. Needs its own route through the reverse proxy (an h2c/HTTP2 upstream), separate from the web UI port. | source for port 9000 |
Environment variables
Environment variables| Variable | Required | What it does | Example | Source |
|---|
WOODPECKER_HOST | Yes | The server's own public address in <scheme>://<hostname> form, no trailing slash. Woodpecker needs to know this to build correct links and OAuth callbacks. | https://ci.example.com | source for WOODPECKER_HOST |
WOODPECKER_AGENT_SECRET | Yes | Shared secret the server and every agent use to authenticate the gRPC connection between them. | openssl rand -hex 32 | source for WOODPECKER_AGENT_SECRET |
WOODPECKER_OPEN | No | Opens registration to anyone who can authenticate through the configured forge. Closed by default; pair with WOODPECKER_ADMIN to name specific admins. | true | source for WOODPECKER_OPEN |
WOODPECKER_GRPC_SECURE | No | Enables TLS on the gRPC connection. Recommended whenever an agent reaches the server over the internet rather than a private network. | true | source for WOODPECKER_GRPC_SECURE |
WOODPECKER_SERVER | Yes | Address of the server's gRPC port that the agent connects to. Set on the agent, not the server. | woodpecker-server:9000 | source for WOODPECKER_SERVER |
Volumes that must persist
Volumes| Path | What is in it | Source |
|---|
/var/lib/woodpecker/ | Bundled SQLite database holding users, repositories and pipeline metadata. Woodpecker itself does not back this up. | source for /var/lib/woodpecker/ |
/var/run/docker.sock (woodpecker-agent) | Mounted into the agent so it can run pipeline steps as Docker containers using the local backend. | source for /var/run/docker.sock |
Behind a reverse proxy
- The web UI (port 8000) and gRPC (port 9000) need separate routes. A Traefik example exposes them as two routers on two different hostnames, with the gRPC router set to scheme h2c. source for this reverse-proxy note
- For nginx, disable buffering (proxy_buffering off, chunked_transfer_encoding off) on the web UI location, or pipeline logs stop streaming live. source for this reverse-proxy note
- Caddy proxies gRPC by pointing at h2c://woodpecker-server:9000 on its own hostname, separate from the WebUI reverse_proxy block. source for this reverse-proxy note
- WOODPECKER_HOST must exactly match what the proxy serves, including scheme; a mismatch breaks forge OAuth callbacks even when the UI otherwise loads. source for this reverse-proxy note
What it needs alongside it
Dependencies| Dependency | Why | Source |
|---|
| SQLite (default), MySQL/MariaDB or PostgreSQL | SQLite needs no extra container. Woodpecker does not create the database itself for MySQL/PostgreSQL, and performs no automatic backups for any engine. | source for SQLite (default), MySQL/MariaDB or PostgreSQL |
Release timeline
If it is not coming up
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-09-07. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.
Other app references
All app references