2021-09-16 16:50:53 +00:00
# Setup
A Woodpecker deployment consists of two parts:
2022-08-31 23:52:52 +00:00
2022-01-24 15:11:00 +00:00
- A server which is the heart of Woodpecker and ships the webinterface.
2021-09-16 16:50:53 +00:00
- 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:
2022-08-31 23:52:52 +00:00
- Using [docker-compose ](#docker-compose ) with the official [container images ](../80-downloads.md#docker-images )
- By deploying to a [Kubernetes ](./80-kubernetes.md ) with manifests or Woodpeckers official Helm charts
- Using [binaries ](../80-downloads.md )
2021-09-16 16:50:53 +00:00
### 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:
2021-10-28 19:02:43 +00:00
- woodpecker-server-data:/var/lib/woodpecker/
2021-09-11 15:10:32 +00:00
environment:
- WOODPECKER_OPEN=true
- WOODPECKER_HOST=${WOODPECKER_HOST}
- WOODPECKER_GITHUB=true
- WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
- WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
Clean up config environment variables for server and agent (#218)
The goal here is to make consistent use of configuration environment variables prefixed `WOODPECKER_`. Where several variants existed, this PR aims to remove all but one option, leaving the most explicit.
This PR only changes server and agent code, but not documentation, in order to keep the PR digestible. Once we have consensus that this is correct, I'll change docs accordingly.
User (rather: admin) facing changes in this PR:
- In general, support for all server and agent config environment variables (env vars) starting with `DRONE_` is removed. The according `WOODPECKER_*` variables must be used instead.
- The env var `WOODPECKER_HOST` replaces `DRONE_HOST`, and `DRONE_SERVER_HOST`.
- The env var `WOODPECKER_AGENT_SECRET` is used to configure the shared secret which agents use to authenticate against the server. It replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD`, and `DRONE_AGENT_SECRET`.
- The env var `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
- The env var `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
2021-09-28 13:43:44 +00:00
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
2021-09-11 15:10:32 +00:00
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
Clean up config environment variables for server and agent (#218)
The goal here is to make consistent use of configuration environment variables prefixed `WOODPECKER_`. Where several variants existed, this PR aims to remove all but one option, leaving the most explicit.
This PR only changes server and agent code, but not documentation, in order to keep the PR digestible. Once we have consensus that this is correct, I'll change docs accordingly.
User (rather: admin) facing changes in this PR:
- In general, support for all server and agent config environment variables (env vars) starting with `DRONE_` is removed. The according `WOODPECKER_*` variables must be used instead.
- The env var `WOODPECKER_HOST` replaces `DRONE_HOST`, and `DRONE_SERVER_HOST`.
- The env var `WOODPECKER_AGENT_SECRET` is used to configure the shared secret which agents use to authenticate against the server. It replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD`, and `DRONE_AGENT_SECRET`.
- The env var `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
- The env var `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
2021-09-28 13:43:44 +00:00
- WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
2021-09-11 15:10:32 +00:00
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
- [...]
Clean up config environment variables for server and agent (#218)
The goal here is to make consistent use of configuration environment variables prefixed `WOODPECKER_`. Where several variants existed, this PR aims to remove all but one option, leaving the most explicit.
This PR only changes server and agent code, but not documentation, in order to keep the PR digestible. Once we have consensus that this is correct, I'll change docs accordingly.
User (rather: admin) facing changes in this PR:
- In general, support for all server and agent config environment variables (env vars) starting with `DRONE_` is removed. The according `WOODPECKER_*` variables must be used instead.
- The env var `WOODPECKER_HOST` replaces `DRONE_HOST`, and `DRONE_SERVER_HOST`.
- The env var `WOODPECKER_AGENT_SECRET` is used to configure the shared secret which agents use to authenticate against the server. It replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD`, and `DRONE_AGENT_SECRET`.
- The env var `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
- The env var `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
2021-09-28 13:43:44 +00:00
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
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
environment:
2021-09-27 22:04:52 +00:00
- [...]
Clean up config environment variables for server and agent (#218)
The goal here is to make consistent use of configuration environment variables prefixed `WOODPECKER_`. Where several variants existed, this PR aims to remove all but one option, leaving the most explicit.
This PR only changes server and agent code, but not documentation, in order to keep the PR digestible. Once we have consensus that this is correct, I'll change docs accordingly.
User (rather: admin) facing changes in this PR:
- In general, support for all server and agent config environment variables (env vars) starting with `DRONE_` is removed. The according `WOODPECKER_*` variables must be used instead.
- The env var `WOODPECKER_HOST` replaces `DRONE_HOST`, and `DRONE_SERVER_HOST`.
- The env var `WOODPECKER_AGENT_SECRET` is used to configure the shared secret which agents use to authenticate against the server. It replaces `WOODPECKER_SECRET`, `DRONE_SECRET`, `WOODPECKER_PASSWORD`, `DRONE_PASSWORD`, and `DRONE_AGENT_SECRET`.
- The env var `WOODPECKER_DATABASE_DRIVER` replaces `DRONE_DATABASE_DRIVER` and `DATABASE_DRIVER`.
- The env var `WOODPECKER_DATABASE_DATASOURCE` replaces `DRONE_DATABASE_DATASOURCE` and `DATABASE_CONFIG`.
2021-09-28 13:43:44 +00:00
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
2021-09-11 15:10:32 +00:00
```
## Authentication
2022-04-06 15:15:28 +00:00
Authentication is done using OAuth and is delegated to your forge which is configured by using environment variables. The example above demonstrates basic GitHub integration.
2021-09-11 15:10:32 +00:00
2022-08-31 23:52:52 +00:00
See the complete reference for all supported forges [here ](./11-forges/10-overview.md ).
2021-09-11 15:10:32 +00:00
## Database
2022-08-31 23:52:52 +00:00
By default Woodpecker uses a sqlite database which requires zero installation or configuration. See the [database settings ](./30-database.md ) page to further configure it or use MySQL or Postgres.
2021-09-11 15:10:32 +00:00
## SSL
2022-08-31 23:52:52 +00:00
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide ](./60-ssl.md ).
2021-09-11 15:10:32 +00:00
## Metrics
2022-08-31 23:52:52 +00:00
A [Prometheus endpoint ](./90-prometheus.md ) is exposed.
2021-09-11 15:10:32 +00:00
## Behind a proxy
2022-08-31 23:52:52 +00:00
See the [proxy guide ](./70-proxy.md ) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.