Improve administration docs (#307)

* Improve administration docs

* Correct docker image names

* Update docs README

Co-authored-by: 6543 <6543@obermui.de>
This commit is contained in:
Anbraten 2021-09-16 18:50:53 +02:00 committed by GitHub
parent a07f120d12
commit 2bfeb9e1fa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 154 additions and 136 deletions

View file

@ -26,8 +26,10 @@ This command generates static content into the `build` directory and can be serv
### Deployment
```
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```
Deployment happen via [CI](https://github.com/woodpecker-ci/woodpecker/blob/d59fdb4602bfdd0d00078716ba61b05c02cbd1af/.woodpecker/docs.yml#L8-L30) to [woodpecker-ci.github.io](https://woodpecker-ci.github.io).
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
To manually build the website and push it exec:
```sh
GIT_USER=woodpecker-bot USE_SSH=true DEPLOYMENT_BRANCH=master yarn deploy
```

View file

@ -1,8 +1,25 @@
# Server Setup
# 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.
## Installation
The below [docker-compose](https://docs.docker.com/compose/) configuration can be used to start Woodpecker with a single agent.
You can install Woodpecker [images](/docs/downloads#docker-images) on multiple ways:
- Using [docker-compose](https://docs.docker.com/compose/)
- By deploying to a [Kubernetes](/docs/administration/kubernetes) with manifests or a Helm charts
- 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.
It relies on a number of environment variables that you must set before running `docker-compose up`. The variables are described below.
@ -41,16 +58,7 @@ volumes:
woodpecker-server-data:
```
> Each agent is able to process one build 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.
Woodpecker needs to know its own address.
You must therefore provide the address in `<scheme>://<hostname>` format. Please omit trailing slashes.
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
services:
@ -65,7 +73,7 @@ services:
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
Agents require access to the host machine's Docker daemon.
As agents run pipeline steps as docker containers they require access to the host machine's Docker daemon:
```diff
services:
@ -78,7 +86,7 @@ services:
+ - /var/run/docker.sock:/var/run/docker.sock
```
Agents require the server address for agent-to-server communication.
Agents require the server address for agent-to-server communication:
```diff
services:
@ -94,9 +102,7 @@ services:
- WOODPECKER_SECRET=${WOODPECKER_SECRET}
```
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`.
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
services:
@ -121,31 +127,15 @@ services:
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.
See the complete reference for [GitHub](/docs/administration/vcs/github), [Bitbucket Cloud](/docs/administration/vcs/bitbucket), [Bitbucket Server](/docs/administration/vcs/bitbucket_server) and [Gitlab](/docs/administration/vcs/gitlab).
See the complete reference for all supported version control systems [here](/docs/administration/vcs/overview).
## Database
Woodpecker mounts a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
See the [database settings](/docs/administration/database) page to configure Postgresql or MySQL as database.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
+ volumes:
+ - woodpecker-server-data:/var/lib/drone/
restart: always
```
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.
## SSL
Woodpecker supports ssl configuration by mounting certificates into your container. See the [SSL guide](/docs/administration/ssl).
Automated [Lets Encrypt](/docs/administration/lets-encrypt) is also supported.
Woodpecker supports ssl configuration by using Let's encrypt or by using own certificates. See the [SSL guide](/docs/administration/ssl).
## Metrics
@ -154,7 +144,3 @@ 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.
## Deploy to Kubernetes
See the [Kubernetes guide](/docs/administration/kubernetes) if you want to deploy Woodpecker to your Kubernetes cluster.

View file

@ -0,0 +1,3 @@
# Agent configuration
TODO

View file

@ -46,35 +46,35 @@ Please use this screenshot for reference:
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_GITHUB=true
`WOODPECKER_GITHUB=true`
: Set to true to enable the GitHub driver.
WOODPECKER_GITHUB_URL=`https://github.com`
`WOODPECKER_GITHUB_URL=https://github.com`
: GitHub server address.
WOODPECKER_GITHUB_CLIENT
`WOODPECKER_GITHUB_CLIENT`
: GitHub oauth2 client id.
WOODPECKER_GITHUB_SECRET
`WOODPECKER_GITHUB_SECRET`
: GitHub oauth2 client secret.
WOODPECKER_GITHUB_SCOPE=repo,repo:status,user:email,read:org
`WOODPECKER_GITHUB_SCOPE=repo,repo:status,user:email,read:org`
: Comma-separated GitHub oauth scope.
WOODPECKER_GITHUB_GIT_USERNAME
`WOODPECKER_GITHUB_GIT_USERNAME`
: Optional. Use a single machine account username to clone all repositories.
WOODPECKER_GITHUB_GIT_PASSWORD
`WOODPECKER_GITHUB_GIT_PASSWORD`
: Optional. Use a single machine account password to clone all repositories.
WOODPECKER_GITHUB_PRIVATE_MODE=false
`WOODPECKER_GITHUB_PRIVATE_MODE=false`
: Set to true if GitHub is running in private mode.
WOODPECKER_GITHUB_MERGE_REF=true
`WOODPECKER_GITHUB_MERGE_REF=true`
: Set to true to use the `refs/pulls/%d/merge` vs `refs/pulls/%d/head`
WOODPECKER_GITHUB_CONTEXT=continuous-integration/drone
`WOODPECKER_GITHUB_CONTEXT=continuous-integration/woodpecker`
: Customize the GitHub status message context
WOODPECKER_GITHUB_SKIP_VERIFY=false
`WOODPECKER_GITHUB_SKIP_VERIFY=false`
: Set to true to disable SSL verification.

View file

@ -37,35 +37,38 @@ services:
## Registration
TODO
Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea.<host>/user/settings/`. It is very import the authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
![gitea oauth setup](gitea_oauth.gif)
## Configuration
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_GITEA=true
`WOODPECKER_GITEA=true`
: Set to true to enable the Gitea driver.
WOODPECKER_GITEA_URL=`https://try.gitea.io`
`WOODPECKER_GITEA_URL=https://try.gitea.io`
: Gitea server address.
WOODPECKER_GITEA_CLIENT
`WOODPECKER_GITEA_CLIENT`
: Gitea oauth2 client id.
WOODPECKER_GITEA_SECRET
`WOODPECKER_GITEA_SECRET`
: Gitea oauth2 client secret.
WOODPECKER_GITEA_CONTEXT=continuous-integration/drone
`WOODPECKER_GITEA_CONTEXT=continuous-integration/woodpecker`
: Customize the Gitea status message context
WOODPECKER_GITEA_GIT_USERNAME
`WOODPECKER_GITEA_GIT_USERNAME`
: Optional. Use a single machine account username to clone all repositories.
WOODPECKER_GITEA_GIT_PASSWORD
`WOODPECKER_GITEA_GIT_PASSWORD`
: Optional. Use a single machine account password to clone all repositories.
WOODPECKER_GITEA_PRIVATE_MODE=true
`WOODPECKER_GITEA_PRIVATE_MODE=true`
: Set to true if Gitea is running in private mode.
WOODPECKER_GITEA_SKIP_VERIFY=false
`WOODPECKER_GITEA_SKIP_VERIFY=false`
: Set to true to disable SSL verification.

View file

@ -37,28 +37,28 @@ services:
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_GITLAB=true
`WOODPECKER_GITLAB=true`
: Set to true to enable the GitLab driver.
WOODPECKER_GITLAB_URL=`https://gitlab.com`
`WOODPECKER_GITLAB_URL=https://gitlab.com`
: GitLab Server address.
WOODPECKER_GITLAB_CLIENT
`WOODPECKER_GITLAB_CLIENT`
: GitLab oauth2 client id.
WOODPECKER_GITLAB_SECRET
`WOODPECKER_GITLAB_SECRET`
: GitLab oauth2 client secret.
WOODPECKER_GITLAB_GIT_USERNAME
`WOODPECKER_GITLAB_GIT_USERNAME`
: Optional. Use a single machine account username to clone all repositories.
WOODPECKER_GITLAB_GIT_PASSWORD
`WOODPECKER_GITLAB_GIT_PASSWORD`
: Optional. Use a single machine account password to clone all repositories.
WOODPECKER_GITLAB_SKIP_VERIFY=false
`WOODPECKER_GITLAB_SKIP_VERIFY=false`
: Set to true to disable SSL verification.
WOODPECKER_GITLAB_PRIVATE_MODE=false
`WOODPECKER_GITLAB_PRIVATE_MODE=false`
: Set to true if GitLab is running in private mode.
## Registration

View file

@ -38,13 +38,13 @@ services:
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_BITBUCKET=true
`WOODPECKER_BITBUCKET=true`
: Set to true to enable the Bitbucket driver.
WOODPECKER_BITBUCKET_CLIENT
`WOODPECKER_BITBUCKET_CLIENT`
: Bitbucket oauth2 client id
WOODPECKER_BITBUCKET_SECRET
`WOODPECKER_BITBUCKET_SECRET`
: Bitbucket oauth2 client secret
## Registration

View file

@ -113,23 +113,23 @@ Please use http://woodpecker.mycompany.com/authorize as the Authorization callba
This is a full list of configuration options. Please note that many of these options use default configuration values that should work for the majority of installations.
WOODPECKER_STASH=true
`WOODPECKER_STASH=true`
: Set to true to enable the Bitbucket Server (Stash) driver.
WOODPECKER_STASH_URL
`WOODPECKER_STASH_URL`
: Bitbucket Server address.
WOODPECKER_STASH_CONSUMER_KEY
`WOODPECKER_STASH_CONSUMER_KEY`
: Bitbucket Server oauth1 consumer key
WOODPECKER_STASH_CONSUMER_RSA
`WOODPECKER_STASH_CONSUMER_RSA`
: Bitbucket Server oauth1 private key file
WOODPECKER_STASH_CONSUMER_RSA_STRING
`WOODPECKER_STASH_CONSUMER_RSA_STRING`
: Bibucket Server oauth1 private key as a string
WOODPECKER_STASH_GIT_USERNAME
`WOODPECKER_STASH_GIT_USERNAME`
: Machine account username used to clone repositories.
WOODPECKER_STASH_GIT_PASSWORD
`WOODPECKER_STASH_GIT_PASSWORD`
: Machine account password used to clone repositories.

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

View file

@ -1,6 +1,22 @@
# Databases
This guide provides instructions for using alternate storage engines. Please note this is optional. The default storage engine is an embedded SQLite database which requires zero installation or configuration.
The default database engine of Woodpecker is an embedded SQLite database which requires zero installation or configuration. But you can replace it with a MySQL or Postgres database.
## Configure sqlite
By default Woodpecker uses a sqlite database stored under `/var/lib/drone/`. You can mount a [data volume](https://docs.docker.com/storage/volumes/#create-and-manage-volumes) to persist the sqlite database.
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
- 80:8000
- 9000
+ volumes:
+ - woodpecker-server-data:/var/lib/drone/
restart: always
```
## Configure MySQL

View file

@ -1,42 +0,0 @@
# Let's Encrypt
Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
You can enable Let's Encrypt by making the following modifications to your server configuration:
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
+ - 80:80
+ - 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
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_LETS_ENCRYPT=true
```
Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://foo.com` the certificate is requested for `foo.com`.
>Once enabled you can visit your website at both the http and the https address
## Certificate Cache
Woodpecker writes the certificates to the below directory:
```
/var/lib/drone/golang-autocert
```
## Certificate Updates
Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.

View file

@ -1,5 +1,54 @@
# SSL
Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with
renewal or provide your own SSL certificates.
## Let's Encrypt
Woodpecker supports automated SSL configuration and updates using Let's Encrypt.
You can enable Let's Encrypt by making the following modifications to your server configuration:
```diff
services:
woodpecker-server:
image: woodpeckerci/woodpecker-server:latest
ports:
+ - 80:80
+ - 443:443
- 9000:9000
volumes:
- /var/lib/drone:/var/lib/drone/
restart: always
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_LETS_ENCRYPT=true
```
Note that Woodpecker uses the hostname from the `WOODPECKER_HOST` environment variable when requesting certificates. For example, if `WOODPECKER_HOST=https://foo.com` the certificate is requested for `foo.com`.
>Once enabled you can visit your website at both the http and the https address
### Certificate Cache
Woodpecker writes the certificates to the below directory:
```
/var/lib/drone/golang-autocert
```
### Certificate Updates
Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.
## SSL with own certificates
Woodpecker supports ssl configuration by mounting certificates into your container.
```diff
@ -68,12 +117,12 @@ services:
+ - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.foo.com/server.key
```
## Certificate Chain
### Certificate Chain
The most common problem encountered is providing a certificate file without the intermediate chain.
> LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.
## Certificate Errors
### Certificate Errors
SSL support is provided using the [ListenAndServeTLS](https://golang.org/pkg/net/http/#ListenAndServeTLS) function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.

View file

@ -1,22 +1,23 @@
# Downloads
## Executables
## Binaries
[Latest release](https://github.com/woodpecker-ci/woodpecker/releases/latest)
## Docker images
``` bash
# server
docker pull woodpecker-ci/woodpecker-server:latest
docker pull woodpecker-ci/woodpecker-server:latest-alpine
docker pull woodpeckerci/woodpecker-server:latest
docker pull woodpeckerci/woodpecker-server:latest-alpine
# agent
docker pull woodpecker-ci/woodpecker-agent:latest
docker pull woodpecker-ci/woodpecker-agent:latest-alpine
docker pull woodpeckerci/woodpecker-agent:latest
docker pull woodpeckerci/woodpecker-agent:latest-alpine
# cli
docker pull woodpecker-ci/woodpecker-cli:latest
docker pull woodpecker-ci/woodpecker-cli:latest-alpine
docker pull woodpeckerci/woodpecker-cli:latest
docker pull woodpeckerci/woodpecker-cli:latest-alpine
```
## APK, DEB, RPM

View file

@ -54,7 +54,7 @@ module.exports = {
},
{
label: 'Server setup',
to: '/docs/administration/server-setup',
to: '/docs/administration/setup',
},
{
label: 'FAQ',