Inline the "Prerequisite" Chapter

This will make the documentation easier to understand, because topics such as db, oauth, domain, registry, certs., etc. can now be covered completely by their own chapter.

This also allows to focus on the relevant prerequisites for the environment of choice. For example, on GCP the build-in docker registry is not relevant.

Author: meysholdt

src/docs/menu.ts

@@ -203,10 +203,6 @@ export const MENU: MenuEntry[] = [
         "Gitpod Self-Hosted",
         "self-hosted/latest/self-hosted",
         [
-            M(
-                "Prerequisites",
-                "self-hosted/latest/install/prepare-installation/"
-            ), 
             M(
                 "Install on Vanilla Kubernetes",
                 "self-hosted/latest/install/install-on-kubernetes/"
@@ -219,6 +215,10 @@ export const MENU: MenuEntry[] = [
                 "OAuth",
                 "self-hosted/latest/install/oauth/"
             ),
+            M(
+                "Domain",
+                "self-hosted/latest/install/domain/"
+            ),
             M(
                 "HTTPS Certificates",
                 "self-hosted/latest/install/https-certs/"

src/docs/self-hosted/0.4.0/install/database.md

@@ -4,6 +4,13 @@ url: /docs/self-hosted/0.4.0/install/database/
 
 
 #### Database
+Gitpod uses a MySQL database to store user data. By default Gitpod ships with a MySQL database built-in. If you operate your own MySQL database (which we'd recommend in a production setting) you can use that one. You have the following options:
+
+* Integrated database: If not disabled, this MySQL database is installed in a Kubernetes pod as a part of Gitpod’s Helm chart.
+The database uses a Kubernetes PersistentVolume. We do not recommend using this option fo a production setting.
+
+* Own MySQL database: Gitpod requires MySQL in version 5.7 or newer.
+
 This chart installs a MySQL database which gets Gitpod up and running but is not suitable for production (the data is lost on each restart of the DB pod). To connect to a porper MySQL installation:
    - initialize your MySQL database using the SQL files in `database/`. E.g. in a mysql session connected to your database server run:
      ```

src/docs/self-hosted/0.4.0/install/docker-registry.md

@@ -4,7 +4,15 @@ url: /docs/self-hosted/0.4.0/install/docker-registry/
 
 # Docker Registry
 
-Gitpod uses a Docker registry to push the workspace images it builds.
+Gitpod builds Docker images during workspace startup. This enables custom Dockerfiles as part of your workspace config, but is also required for Gitpod itself to function.
+To this end, Gitpod requires a container registry where it can push the images it builds.
+
+By default Gitpod ships with a built-in Docker registry. If you operate your own Docker registry (which we'd recommend in a production setting) you can use that one. You have the following options:
+
+* Integrated docker registry: If not disabled, this docker registry is installed in a Kubernetes Pod as a dependency of Gitpod’s Helm chart.
+  The docker registry requires a Kubernetes PersistentVolume. This registry is not recommended to be used for production.
+* Own docker registry: Gitpod can connect to your own docker registry. Compared to its built-in counterpart this enables performance gains and access to otherwise private images.
+
 This helm chart can either deploy its own registry (default but requires [HTTPS certs](../https-certs/)) or use an existing one.
 To connect to an existing Docker registry, do the following steps:
 

src/docs/self-hosted/0.4.0/install/domain.md

@@ -0,0 +1,19 @@
+---
+url: /docs/self-hosted/0.4.0/install/domain/
+---
+
+# Domain
+
+Gitpod requires a domain resolvable by some nameserver (typically a public domain name, e.g. `your-domain.com`).
+As Gitpod launches services and workspaces on additional subdomains it also needs two wildcard domains.
+For example:
+
+    your-domain.com
+    *.your-domain.com
+    *.ws.your-domain.com
+
+Installing Gitpod on a subdomain works as well. For example:
+
+    gitpod.your-domain.com
+    *.gitpod.your-domain.com
+    *.gitpod.ws.your-domain.com

src/docs/self-hosted/0.4.0/install/https-certs.md

@@ -2,9 +2,13 @@
 url: /docs/self-hosted/0.4.0/install/https-certs/
 ---
 
+
 ### HTTPS certificates
 
-Gitpod needs HTTPS certificates, your own Docker registry, or both to function properly. If you don't have certificates, but a Docker registry available, jump to the [next step](../docker-registry/).
+
+While we highly recommend operating Gitpod using HTTPS, Gitpod is able to run on insecure HTTP.
+If you use Gitpod's inernal docker registry, the downside of not using HTTPS is that Kubernetes won't be able to pull images from the registry because it considers the registry insecure.
+You can either resort to using an [external registry](#docker-registry-optional) or use HTTPS. For running Gitpod on insecure HTTP, no HTTPS certificates are needed and you can skip this section.
 
 > Important: The HTTPS certificates for your domain must include `your-domain.com`, `*.your-domain.com` and `*.ws.your-domain.com`. Beware that wildcard certificates are valid for one level only (i.e. `*.a.com` is not valid for `c.b.a.com`).
 
@@ -25,7 +29,12 @@ openssl dhparam -out secrets/https-certificates/dhparams.pem 2048
 ```
 
 #### Using Let's Encrypt
-If you do not have HTTPS certificates for your domain already, you can generate some using [Let's Encrypt](https://medium.com/@saurabh6790/generate-wildcard-ssl-certificate-using-lets-encrypt-certbot-273e432794d7).
+
+The most accessible means of obtaining HTTPS certificates is using [Let's Encrypt](https://letsencrypt.org/) which provides free certificats to anybody who can prove ownership of a domain.
+Gitpod requires [wildcard certificates](https://en.wikipedia.org/wiki/Wildcard_certificate) (e.g. `*.ws.your-domain.com`) which [can be obtained via Let's Encrypt](https://community.letsencrypt.org/t/acme-v2-production-environment-wildcards/55578) but require [proof of ownership via DNS](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge).
+There is a [plethora of tutorials](https://www.google.com/search?q=letsencrypt+wildcard) how to [generate wildcard certificates](https://medium.com/@saurabh6790/generate-wildcard-ssl-certificate-using-lets-encrypt-certbot-273e432794d7) using Let's Encrypt.
+Things get considerably easier when your domain is registered with a service for which a [Certbot DNS plugin exists](https://certbot.eff.org/docs/using.html#dns-plugins).
+
 Asuming you have `certbot` installed, the following script will generate and configure the required certificates (notice the placeholders):
 ```bash
 export DOMAIN=your-domain.cm

src/docs/self-hosted/0.4.0/install/install-on-gcp-script.md

@@ -20,10 +20,12 @@ You can install Gitpod self-hosted in your GCP project from within Gitpod. This
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/gitpod-io/self-hosted)
 
 ## Prerequisites
-- Ensure you have the [general installation prerequisites](../prepare-installation/) available.
+- A Google Cloud project
+- [Domain](../domain)
 - [Google Cloud SDK](https://cloud.google.com/sdk/install)
 - [Go (at least 1.12)](https://golang.org/doc/install)
-- mysql client
+- MySQL client
+- Optional: [HTTPS Certificates](../https-certs)
 
 ## Configuration
 

src/docs/self-hosted/0.4.0/install/install-on-kubernetes.md

@@ -10,9 +10,14 @@ Gitpod also provides more optimized installations offering better performance fo
 
 ## Prerequisites
 
-- Ensure you have the [general installation prerequisites](../prepare-installation/) available.
+- A Kubernetes Cluster in Version 1.13 or newer.
+- [Domain](../domain)
+- [HTTPS Certificates](../https-certs): Optional, if you use an external docker registry.
 - `kubectl` with access to that cluster.
 - `helm`. We recommend version 3.x. Any version >= 2.11 will also work, but requires you to have [tiller configured](../helm-2x/).
+- Optional: A MySQL Database
+- Optional: A Docker Registry
+- Optional: Buckets Storage, e.g. Minio
 
 ## Configuration
 
@@ -29,17 +34,16 @@ git remote rename origin upstream
 For the rest of this guide we will assume that you are located in the root of a working copy of this repository.
 
 ### Domain name and IP address
-Gitpod requires a domain name which resolves to the IP of your Kubernetes cluster. In this document we'll use `your-domain.com` as example. Set your real domain in the `values.yaml` under `gitpod.hostname`.
+Gitpod requires [domain names](../domain/) which resolve to the IP of your Kubernetes cluster. 
+Set your domain in the `values.yaml` under `gitpod.hostname`.
+
 By default Gitpod deploys a [`LoadBalancer` service](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) as means of ingress.
 If you have a fixed IP address that you want to use, set the `gitpod.components.proxy.loadBalancerIP` field to the external IP of your cluster/load balancer.
 If this field is not set, Kubernetes will assign you a load balancer IP during deployment.
-Once you know your IP address, configure your three domain names to resolve to that IP address:
- - `your-domain.com`
- - `*.your-domain.com`
- - `*.ws.your-domain.com`
+Once you know your IP address, configure your three domain names to resolve to that IP address.
 
 ### OAuth integration
-Gitpod delegates authentication to a configurable [OAuth provider](../prepare-installation/#user-authorization-and-git-integration).
+Gitpod delegates authentication to a configurable OAuth provider.
 
 Follow [the steps](../oauth/) to set up GitHub or GitLab as OAuth provider.
 

src/docs/self-hosted/0.4.0/install/oauth.md

@@ -4,7 +4,18 @@ url: /docs/self-hosted/0.4.0/install/oauth/
 
 # How To integrate Gitpod with OAuth providers
 
-Currently Gitpod supports GitHub, GitHub Enterprise and GitLab.
+Gitpod does not implement user authentication itself, but integrates with other auth provider using [OAuth2](https://oauth.net/2/).
+Usually your Git hosting solution (e.g. GitHub or GitLab) acts as the OAuth auth provider. This way we control access to Gitpod while at
+the same time making sure every user has proper access to their Git repository.
+
+Gitpod supports the following authentication providers:
+* github.com
+* GitHub Enterprise in version 2.16.x and higher
+* gitlab.com
+* GitLab Community Edition in version 11.7.x and higher
+* GitLab Enterprise Edition in version 11.7.x and higher
+* Bitbucket — coming soon
+* Custom Auth Provider – Inquiry TypeFox for a quote
 
 ## GitHub
 To authenticate your users with GitHub you need to create a [GitHub OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).

src/docs/self-hosted/0.4.0/install/prepare-installation.md

@@ -4,7 +4,15 @@ url: /docs/self-hosted/0.4.0/install/storage/
 
 # Workspace Storage
 
-Gitpod creates a backup of workspaces when they're shut down. 
+Gitpod uses bucket storage to persist the contents of workspaces. Each workspace is tarballed into a single archive file which is then uploaded to the bucket.
+
+By default Gitpod ships with [MinIO](https://min.io/) as built-in bucket storage. If you operate your own MinIO instance, or have access to Google Cloud Bucket storage you can use that one. You have the following options:
+
+* Integrated MinIO: If not disabled, Gitpod installs MinIO in Kubernetes as a dependency of Gitpod’s helm charts.
+  MinIO itself can serve as a [gateway](https://github.com/minio/minio/tree/master/docs/gateway) to other storage providers.
+  When storing the data itself, MinIO relies on a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) which in turn supports a [wide range of storage backends](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes).
+* Bring your own storage bucket: Gitpod can be configured to connect to your own installation of MinIO or Google Cloud Storage compatible storage solution.
+
 This helm chart ships with a [MinIO](https://min.io/) installation for this purpose. 
 Alternatively, you can connect to your own [MinIO](https://min.io/) installation using
  - `echo values/minio.yaml >> configuration.txt`