Git and CI, checked 2026-10-17
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
- Image:
docker.io/woodpeckerci/woodpecker-server - Tags:
v3.19.0,v3.19,v3 - Licence: Apache-2.0
- Source: https://github.com/woodpecker-ci/woodpecker
- Docs: https://woodpecker-ci.org/docs/intro
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
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
WOODPECKER_HOST | Yes | The server's own public address as a full URL with scheme, hostname, non-default port and any path prefix. 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
| 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
| 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
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v3.19.0 | 2026-10-07 | No | Fixes matrix env var injection into the default clone step; adds server-side enforced agent labels and custom shell paths for the local backend. | source for release v3.19.0 |
v3.18.1 | 2026-09-08 | No | Adds timezone data to the images, speeds up the log dedupe migration and fixes workflow-level when.status handling. | source for release v3.18.1 |
v3.18.0 | 2026-08-24 | Yes | Contains a migration that alters log storage; upstream recommends a backup and extra downtime before upgrading. | source for release v3.18.0 |
v3.17.0 | 2026-07-31 | No | Feature release on the 3.x line. | source for release v3.17.0 |
v3.16.0 | 2026-06-27 | No | Feature release on the 3.x line. | source for release v3.16.0 |
v3.15.0 | 2026-05-28 | No | Feature release on the 3.x line. | source for release v3.15.0 |
v3.14.1 | 2026-05-12 | No | Security patch, crediting researchers who reported and fixed the issue. | source for release v3.14.1 |
If it is not coming up
- WebSocket connection to 'wss://<your-domain>:6001/app/...' failed (UI shows "WARNING: Cannot connect to real-time service")
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.