mirrors/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-06-26 01:00:51 +00:00
Code Issues Projects Releases Wiki Activity

Rework setup docs (#2630)

Browse source 
Co-authored-by: Anbraten <anton@ju60.de>
This commit is contained in:
qwerty287 2023-10-23 14:37:29 +02:00 committed by GitHub
parent ae2aff9afc
commit 30328e6b2d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 253 additions and 261 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docs/10-intro.md
View file

@ -91,4 +91,4 @@ See [plugin docs](./20-usage/51-plugins/10-plugins.md).
## Continue reading
- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md)
- [Setup your own Woodpecker instance](./30-administration/00-setup.md)
- [Setup your own Woodpecker instance](./30-administration/00-deployment/00-overview.md)

73
docs/docs/30-administration/00-deployment/00-overview.md Normal file
View file

@ -0,0 +1,73 @@
# Overview
A Woodpecker deployment consists of two parts:
- A server which is the heart of Woodpecker and ships the web interface.
- 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 workflows in parallel.
>
> You can add more agents to increase the number of parallel workflows or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent.
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
To find out more about the differences between the two releases, please read the [FAQ](/faq#which-version-of-woodpecker-should-i-use).
## Hardware Requirements
Below are minimal resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resources consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways:
- Using [docker-compose](./10-docker-compose.md) with the official [container images](./10-docker-compose.md#docker-images)
- Using [Kubernetes](./20-kubernetes.md) via the Woodpecker Helm chart
- Using binaries, DEBs or RPMs you can download from [latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Authentication
Authentication is done using OAuth and is delegated to your forge which is configured using environment variables.
See the complete reference for all supported forges [here](../11-forges/10-overview.md).
## Database
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.
## SSL
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](../60-ssl.md). You can also put it behind a [reverse proxy](#behind-a-proxy)
## Metrics
A [Prometheus endpoint](../90-prometheus.md) is exposed.
## Behind a proxy
See the [proxy guide](../70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
In the case you need to use Woodpecker with a URL path prefix (like: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_PATH`](../10-server-config.md#woodpecker_root_path).
## Third-party installation methods
:::info
These installation methods are not officially supported. If you experience issues with them, please open issues in the specific repositories.
:::
- Using [NixOS](./30-nixos.md) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- [Using YunoHost](https://apps.yunohost.org/app/woodpecker)
- [On Cloudron](https://www.cloudron.io/store/org.woodpecker_ci.cloudronapp.html)

154
docs/docs/30-administration/00-deployment/10-docker-compose.md Normal file
View file

@ -0,0 +1,154 @@
# docker-compose
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent.
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/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:latest
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:
```
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
```
Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
They can be configured with ADDR variables:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
```
Reverse proxying can also be [configured for gRPC](../proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
+ - WOODPECKER_GRPC_VERIFY=true # default
```
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
```diff
# docker-compose.yml
version: '3'
services:
[...]
woodpecker-agent:
[...]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-agent:
[...]
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
```
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`:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
```
## Docker images
Image variants:
- The `latest` image is the latest stable release
- The `vX.X.X` images are stable releases
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
- The `next` images are based on the current `main` branch and should not be used for production environments
``` bash
# server
docker pull woodpeckerci/woodpecker-server:latest
docker pull woodpeckerci/woodpecker-server:latest-alpine
# agent
docker pull woodpeckerci/woodpecker-agent:latest
docker pull woodpeckerci/woodpecker-agent:latest-alpine
# cli
docker pull woodpeckerci/woodpecker-cli:latest
docker pull woodpeckerci/woodpecker-cli:latest-alpine
```

10
docs/docs/30-administration/00-deployment/20-kubernetes.md Normal file
View file

@ -0,0 +1,10 @@
# Kubernetes
We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/values.yaml) config files for all available settings.
The chart contains two subcharts, `server` and `agent` which are automatically configured as needed.
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](../22-backends/40-kubernetes.md).

2
docs/docs/30-administration/22-backends/50-nixos.md → docs/docs/30-administration/00-deployment/30-nixos.md
View file

@ -1,4 +1,4 @@
# NixOS Deployment
# NixOS
:::info
Note that this module is not maintained by the woodpecker-developers.

3
docs/docs/30-administration/00-deployment/_category_.yml Normal file
View file

@ -0,0 +1,3 @@
label: 'Deployment'
collapsible: true
collapsed: true

206
docs/docs/30-administration/00-setup.md
View file

@ -1,206 +0,0 @@
# Setup
A Woodpecker deployment consists of two parts:
- A server which is the heart of Woodpecker and ships the web interface.
- 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 steps or set the agent's `WOODPECKER_MAX_WORKFLOWS=1` environment variable to increase the number of parallel workflows for that agent.
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
To find out more about the differences between the two releases, please read the [FAQ](/faq).
## Hardware Requirements
Below are resources requirements for Woodpecker components itself:
| Component | Memory | CPU |
| --------- | ------ | --- |
| Server | 200 MB | 1 |
| Agent | 32 MB | 1 |
Note, that those values do not include the operating system or workload (pipelines execution) resources consumption.
In addition you need at least some kind of database which requires additional resources depending on the selected database system.
## Installation
You can install Woodpecker on multiple ways:
- Using [docker-compose](#docker-compose) with the official [container images](../80-downloads.md#docker-images)
- Using [Kubernetes](#kubernetes) via the Woodpeckers Helm chart
- Using [NixOS](#nixos) via the [NixOS module](https://search.nixos.org/options?channel=unstable&size=200&sort=relevance&query=woodpecker)
- Using [binaries](../80-downloads.md)
### docker-compose
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start a Woodpecker server with a single agent.
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/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:latest
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:
```
Woodpecker needs to know its own address. You must therefore provide the public address of it in `<scheme>://<hostname>` format. Please omit trailing slashes:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_HOST=${WOODPECKER_HOST}
```
Woodpecker can also have its port's configured. It uses a separate port for gRPC and for HTTP. The agent performs gRPC calls and connects to the gRPC port.
They can be configured with ADDR variables:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_ADDR=${WOODPECKER_GRPC_ADDR}
+ - WOODPECKER_SERVER_ADDR=${WOODPECKER_HTTP_ADDR}
```
Reverse proxying can also be [configured for gRPC](./proxy#caddy). If the agents are connecting over the internet, it should also be SSL encrypted. The agent then needs to be configured to be secure:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_GRPC_SECURE=true # defaults to false
+ - WOODPECKER_GRPC_VERIFY=true # default
```
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
```diff
# docker-compose.yml
version: '3'
services:
[...]
woodpecker-agent:
[...]
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication. The agent connects to the server's gRPC port:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-agent:
[...]
environment:
+ - WOODPECKER_SERVER=woodpecker-server:9000
```
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`:
```diff
# docker-compose.yml
version: '3'
services:
woodpecker-server:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
woodpecker-agent:
[...]
environment:
- [...]
+ - WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}
```
### Kubernetes
We recommended to deploy Woodpecker using the [Woodpecker helm chart](https://github.com/woodpecker-ci/helm).
Have a look at the [`values.yaml`](https://github.com/woodpecker-ci/helm/blob/main/values.yaml) config files for all available settings.
The chart contains two subcharts, `server` and `agent` which are automatically configured as needed.
The chart started off with two independent charts but was merged into one to simplify the deployment at start of 2023.
A couple of backend-specific config env vars exists which are described in the [kubernetes backend docs](./22-backends/40-kubernetes.md).
## Authentication
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.
See the complete reference for all supported forges [here](./11-forges/10-overview.md).
## Database
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.
## SSL
Woodpecker supports SSL configuration by using Let's encrypt or by using own certificates. See the [SSL guide](./60-ssl.md).
## Metrics
A [Prometheus endpoint](./90-prometheus.md) is exposed.
## Behind a proxy
See the [proxy guide](./70-proxy.md) if you want to see a setup behind Apache, Nginx, Caddy or ngrok.
In the case you need to use Woodpecker with a URL path prefix (like: https://example.org/woodpecker/), you can use the option [`WOODPECKER_ROOT_PATH`](./10-server-config.md#woodpecker_root_path).

16
docs/docs/30-administration/20-migrate-from-drone.md
View file

@ -1,16 +0,0 @@
# Migrate from Drone to Woodpecker
## Migrate from Drone >= v1.0.0
We currently do not provide a way to do so.
If you are interested or have a custom script to do so, please get in contact with us.
## Migrate from Drone <= v0.8
- Make sure you are already running Drone v0.8
- Upgrade to Woodpecker v0.14.4, migration will be done during startup
- If you are using Sqlite3, rename `drone.sqlite` to `woodpecker.sqlite` and
rename or adjust the mount/folder of the volume from `/var/lib/drone/`
to `/var/lib/woodpecker/`
- Upgrade to Woodpecker v1.0.0, the migration will be performed during
startup

34
docs/docs/80-downloads.md
View file

@ -1,34 +0,0 @@
# Downloads
## Which version of Woodpecker should I use?
Woodpecker is having two different kinds of releases: **stable** and **next**.
To find out more about the differences between the two releases, please read the [FAQ](/faq).
## Binaries & DEB, RPM
[Latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Docker images
Image variants:
- The `latest` image is the latest stable release
- The `vX.X.X` images are stable releases
- The `vX.X` images are based on the current release branch (e.g. `release/v1.0`) and can be used to get bugfixes asap
- The `next` images are based on the current `main` branch and should not be used for production environments
``` bash
# server
docker pull woodpeckerci/woodpecker-server:latest
docker pull woodpeckerci/woodpecker-server:latest-alpine
# agent
docker pull woodpeckerci/woodpecker-agent:latest
docker pull woodpeckerci/woodpecker-agent:latest-alpine
# cli
docker pull woodpeckerci/woodpecker-cli:latest
docker pull woodpeckerci/woodpecker-cli:latest-alpine
```

10
docs/docs/91-migrations.md
View file

@ -120,3 +120,13 @@ Some versions need some changes to the server configuration or the pipeline conf
## 0.14.0
No breaking changes
## From Drone
:::warning
Migration from Drone is only possible if you were running Drone <= v0.8.
:::
1. Make sure you are already running Drone v0.8
2. Upgrade to Woodpecker v0.14.4, migration will be done during startup
3. Upgrade to the latest Woodpecker version. Pay attention to the breaking changes listed above.

4
docs/src/pages/faq.md
View file

@ -18,12 +18,10 @@ Woodpecker is having two different kinds of releases: **stable** and **next**.
The **stable** releases (currently version 1.0) are long-term supported (LTS) stable versions. The stable releases are only getting bugfixes.
The **next** release contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time.
The **next** release contains all bugfixes and features from `main` branch. Normally it should be pretty stable, but as its frequently updated, it might contain some bugs from time to time. There are no binaries for this version.
If you want all (new) features of Woodpecker and are willing to accept some possible bugs from time to time, you should use the next release otherwise use the stable release.
You can find download links for the different releases in the [download section](/docs/downloads).
## How to debug clone issues
(And what to do with an error message like `fatal: could not read Username for 'https://<url>': No such device or address`)