Improve administration docs

docs/README.md

@@ -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
+```

docs/docs/30-administration/10-server-setup.md → docs/docs/30-administration/00-setup.md

@@ -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.

docs/docs/30-administration/11-agent-config.md

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

docs/docs/30-administration/20-vcs/20-github.md

@@ -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.

docs/docs/30-administration/20-vcs/30-gitea.md

@@ -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.

docs/docs/30-administration/20-vcs/40-gitlab.md

@@ -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

docs/docs/30-administration/20-vcs/50-bitbucket.md

@@ -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

docs/docs/30-administration/20-vcs/60-bitbucket_server.md

@@ -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.

docs/docs/30-administration/30-database.md

@@ -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