2021-09-16 16:50:53 +00:00
# Setup
A Woodpecker deployment consists of two parts:
- A server which is the heard of Woodpecker and ships the webinterface.
- Next to one server you can deploy any number of agents which will run the pipelines.
> Each agent is able to process one pipeline step by default.
>
> If you have 4 agents installed and connected to the Woodpecker server, your system will process 4 builds in parallel.
>
> You can add more agents to increase the number of parallel builds or set the agent's `WOODPECKER_MAX_PROCS=1` environment variable to increase the number of parallel builds for that agent.
2021-09-11 15:10:32 +00:00
## Installation
2021-09-27 22:04:52 +00:00
You can install Woodpecker on multiple ways:
- Using [docker-compose ](/docs/administration/setup#docker-compose ) with the official [docker images ](/docs/downloads#docker-images )
- By deploying to a [Kubernetes ](/docs/administration/kubernetes ) with manifests or Woodpeckers official Helm charts
2021-09-16 16:50:53 +00:00
- Using [binaries ](/docs/downloads )
### docker-compose
The below [docker-compose ](https://docs.docker.com/compose/ ) configuration can be used to start a Woodpecker server with a single agent.
2021-09-11 15:10:32 +00:00
It relies on a number of environment variables that you must set before running `docker-compose up` . The variables are described below.
```yaml
# docker-compose.yml
version: '3'
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 8000:8000
volumes:
- woodpecker-server-data:/var/lib/drone/
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
image: woodpeckerci/woodpecker-agent:latest
command: agent
restart: always
depends_on:
- woodpecker-server
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- WOODPECKER_SERVER=woodpecker-server:9000
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
volumes:
woodpecker-server-data:
```
2021-09-16 16:50:53 +00:00
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
2021-09-11 15:10:32 +00:00
```diff
2021-09-27 22:04:52 +00:00
# docker-compose.yml
version: '3'
2021-09-11 15:10:32 +00:00
services:
woodpecker-server:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
environment:
2021-09-27 22:04:52 +00:00
- [...]
2021-09-11 15:10:32 +00:00
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
```
2021-09-16 16:50:53 +00:00
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
2021-09-11 15:10:32 +00:00
```diff
2021-09-27 22:04:52 +00:00
# docker-compose.yml
version: '3'
2021-09-11 15:10:32 +00:00
services:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
woodpecker-agent:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
2021-09-16 16:50:53 +00:00
Agents require the server address for agent-to-server communication:
2021-09-11 15:10:32 +00:00
```diff
2021-09-27 22:04:52 +00:00
# docker-compose.yml
version: '3'
2021-09-11 15:10:32 +00:00
services:
woodpecker-agent:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
```
2021-09-16 16:50:53 +00:00
The server and agents use a shared secret to authenticate communication. This should be a random string of your choosing and should be kept private. You can generate such string with `openssl rand -hex 32` :
2021-09-11 15:10:32 +00:00
```diff
2021-09-27 22:04:52 +00:00
# docker-compose.yml
version: '3'
2021-09-11 15:10:32 +00:00
services:
woodpecker-server:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
environment:
2021-09-27 22:04:52 +00:00
- [...]
2021-09-11 15:10:32 +00:00
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
woodpecker-agent:
2021-09-27 22:04:52 +00:00
[...]
2021-09-11 15:10:32 +00:00
environment:
2021-09-27 22:04:52 +00:00
- [...]
2021-09-11 15:10:32 +00:00
+ - WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
## Authentication
Authentication is done using OAuth and is delegated to one of multiple version control providers, configured using environment variables. The example above demonstrates basic GitHub integration.
2021-09-16 16:50:53 +00:00
See the complete reference for all supported version control systems [here ](/docs/administration/vcs/overview ).
2021-09-11 15:10:32 +00:00
## Database
2021-09-16 16:50:53 +00:00
By default Woodpecker uses a sqlite database which requires zero installation or configuration. See the [database settings ](/docs/administration/database ) page to further configure it or use MySQL or Postgres.
2021-09-11 15:10:32 +00:00
## SSL
2021-09-16 16:50:53 +00:00
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide ](/docs/administration/ssl ).
2021-09-11 15:10:32 +00:00
## Metrics
A [Prometheus endpoint ](/docs/administration/prometheus ) is exposed.
## Behind a proxy
See the [proxy guide ](/docs/administration/proxy ) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.