diff --git a/docs/README.md b/docs/README.md
index 55d0c3ef4..911f1c93b 100644
--- a/docs/README.md
+++ b/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
+```
diff --git a/docs/docs/30-administration/10-server-setup.md b/docs/docs/30-administration/00-setup.md
similarity index 69%
rename from docs/docs/30-administration/10-server-setup.md
rename to docs/docs/30-administration/00-setup.md
index 1da86bd4d..2229b735e 100644
--- a/docs/docs/30-administration/10-server-setup.md
+++ b/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.
diff --git a/docs/docs/30-administration/20-server-config.md b/docs/docs/30-administration/10-server-config.md
similarity index 100%
rename from docs/docs/30-administration/20-server-config.md
rename to docs/docs/30-administration/10-server-config.md
diff --git a/docs/docs/30-administration/11-agent-config.md b/docs/docs/30-administration/11-agent-config.md
new file mode 100644
index 000000000..3e1501253
--- /dev/null
+++ b/docs/docs/30-administration/11-agent-config.md
@@ -0,0 +1,3 @@
+# Agent configuration
+
+TODO
diff --git a/docs/docs/30-administration/20-vcs/20-github.md b/docs/docs/30-administration/20-vcs/20-github.md
index 288da61e1..96f1a4693 100644
--- a/docs/docs/30-administration/20-vcs/20-github.md
+++ b/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.
diff --git a/docs/docs/30-administration/20-vcs/30-gitea.md b/docs/docs/30-administration/20-vcs/30-gitea.md
index eaddaebda..20083b317 100644
--- a/docs/docs/30-administration/20-vcs/30-gitea.md
+++ b/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.
diff --git a/docs/docs/30-administration/20-vcs/40-gitlab.md b/docs/docs/30-administration/20-vcs/40-gitlab.md
index 1c9043072..b1136ea19 100644
--- a/docs/docs/30-administration/20-vcs/40-gitlab.md
+++ b/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
diff --git a/docs/docs/30-administration/20-vcs/50-bitbucket.md b/docs/docs/30-administration/20-vcs/50-bitbucket.md
index 7130926c6..1dfd2036f 100644
--- a/docs/docs/30-administration/20-vcs/50-bitbucket.md
+++ b/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
diff --git a/docs/docs/30-administration/20-vcs/60-bitbucket_server.md b/docs/docs/30-administration/20-vcs/60-bitbucket_server.md
index 9c8ecbba0..35a763a0a 100644
--- a/docs/docs/30-administration/20-vcs/60-bitbucket_server.md
+++ b/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.
diff --git a/docs/docs/30-administration/20-vcs/gitea_oauth.gif b/docs/docs/30-administration/20-vcs/gitea_oauth.gif
new file mode 100644
index 000000000..7478f9385
Binary files /dev/null and b/docs/docs/30-administration/20-vcs/gitea_oauth.gif differ
diff --git a/docs/docs/30-administration/30-database.md b/docs/docs/30-administration/30-database.md
index a6d688b85..b761fe8f8 100644
--- a/docs/docs/30-administration/30-database.md
+++ b/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
 
diff --git a/docs/docs/30-administration/50-lets-encrypt.md b/docs/docs/30-administration/50-lets-encrypt.md
deleted file mode 100644
index d656dceea..000000000
--- a/docs/docs/30-administration/50-lets-encrypt.md
+++ /dev/null
@@ -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.
diff --git a/docs/docs/30-administration/60-ssl.md b/docs/docs/30-administration/60-ssl.md
index aff06a8a3..ee88cd502 100644
--- a/docs/docs/30-administration/60-ssl.md
+++ b/docs/docs/30-administration/60-ssl.md
@@ -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.
diff --git a/docs/docs/80-downloads.md b/docs/docs/80-downloads.md
index a9990d36d..f51374267 100644
--- a/docs/docs/80-downloads.md
+++ b/docs/docs/80-downloads.md
@@ -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
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
index 64fce9937..dea5268bb 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -54,7 +54,7 @@ module.exports = {
             },
             {
               label: 'Server setup',
-              to: '/docs/administration/server-setup',
+              to: '/docs/administration/setup',
             },
             {
               label: 'FAQ',