first part of installation_instructions changed

docs/installation_instructions.md

@@ -28,51 +28,144 @@ machine.**
   * at least 20GB of disk space for installation, plus more for application
     data;
   * root ssh access.
+* A trusted local machine to run the installer on:
+  * You need [virtualenv](https://virtualenv.pypa.io/en/stable/) to make sure we
+    don't change any of your other projects. This can be installed by running
+    `pip3 install --user virtualenv` or `apt install virtualenv`
 
 ### DNS entries
 
 First, begin with creating DNS records for your cluster. It's important to
 start with configuring DNS because depending on your DNS setup/provider, it
-takes a while to propagate. You need one dedicated subdomain entry and a
+takes a while to propagate. You need one dedicated (sub)domain entry and a
 wildcard entry for everything inside it. For example, create an A record for
 these domains:
 
 - oas.example.org
 - \*.oas.example.org
 
-and make them point to your machine's public IP address.
+and make them point to your VPS's public IP address.
 
-## Configure your cluster
+## Install OpenAppStack command line tool
 
-On your **local machine**, clone the OAS bootstrap repo:
+On your **local machine**, clone the OpenAppStack git repository:
 
     $ git clone https://open.greenhost.net/openappstack/openappstack.git
 
-Copy `ansible/inventory.yml.example` to `ansible/inventory.yml` and edit it to
-reflect your cluster.
+Next, install the OpenAppStack CLI client by running the following commands: 
 
-Also copy `ansible/group_vars/all/settings.yml.example` to
-`ansible/group_vars/all/settings.yml` and edit as you see fit.
+First, create a python virtual environment called "env" that uses python 3. This
+makes sure we don't change any of your other python projects.
 
-### Prerequisites
+    $ virtualenv env -p python3
+    $ . env/bin/activate    # activate the virtual environment
+    $ pip install -r requirements.txt
 
-* You need `ansible >= 2.7` installed on your workstation to run the bootstrap
-  scripts. Please install it using your system package manager.
+*Hint: if you get a [segmentation
+fault](https://bitbucket.org/cffi/cffi/issues/272/segfault-while-installing-via-pip)
+using above command, you can add `--no-use-wheel` to it.*
 
-  In the case your system package manager doesn't provide that particular
-  ansible version, you can install it via the python package manager like this:
+Now you can run the OpenAppStack CLI as follows: 
 
-  ```
-  pip3 install --user -r ansible/requirements.txt
-  ```
+    $ python -m openappstack CLUSTER_NAME
 
-  Hint: if you have several python projects on your computer, consider using
-  [virtualenv](https://virtualenv.pypa.io/en/stable/)
+The CLI *always* needs a `CLUSTER_NAME` argument. Even for getting subcommand
+help messages.
 
-  Hint: if you get a [segmentation
-  fault](https://bitbucket.org/cffi/cffi/issues/272/segfault-while-installing-via-pip)
-  using above command, you can add `--no-use-wheel` to it.
+## Install OpenAppStack
 
+Setting up OpenAppStack on your VPS happens in three steps: 
+
+1. **Set up cluster**
+
+   Create configuration files, and optionally create VPS
+2. **Install OpenAppStack**
+
+   This installs Kubernetes and all the other software that comes with
+   OpenAppStack. See [Usage](#usage) for more information on which applications
+   are installed.
+3. **Validate setup**
+
+   This runs a test in the browser to validate that the installation was
+   successful.
+
+### Set up cluster
+
+To set up your cluster, use the `create` subcommand of the OpenAppStack CLI.
+First, think of a name for your cluster. Then run the following command to get
+information about the `create` subcommand: 
+
+    $ python -m openappstack CLUSTER_NAME create --help
+
+Replace `CLUSTER_NAME` with the name you thought of.
+
+There are two options to create a cluster: 
+
+- At Greenhost:
+  - For this to work, you need to have an API key with Customer rights.
+    1. In the Cosmos service centre, click your name on the top right corner
+    2. Go to "User settings" 
+    3. Click "API keys"
+    4. Click "New API key"
+    5. Click "Generate new key"
+    6. Give the key "Customer", "CloudCustomer" or "API" access rights (this
+       depends on what righs your user has. Any of these three is fine)
+    7. Copy the generated key and run export it to this variable in a terminal:
+
+       ```
+       $ export COSMOS_API_TOKEN=paste your API key here
+       ```
+    8. In *the same terminal*, you can now use the `create` subcommand
+  1. Based on an already existing [Greenhost](https://greenhost.net) or
+     [Eclips.is](https://portal.eclips.is/portal/) VPS, using the `--droplet-id`
+     argument.
+
+     Find the ID of your VPS either in the Greenhost Cosmos interface
+     (it's the numeric part of the URL in the "Manage VPS" screen).
+
+  2. By creating a new VPS through the API, using the `--create-droplet`
+     argument
+     - Make sure to also provide the `--hostname` and `--ssh-key-id` arguments.
+
+       You can find your SSH key ID by going to VPS Cloud -> SSH keys and
+       checking the link under "Show key". The numerical part is your SSH key
+       ID.
+
+       *Note: You can also use the API to list ssh keys and find it there. Read the
+       [Eclips.is API
+       documentation](https://portal.eclips.is/portal/cloud/ApiDoc#/default) or
+       [Greenhost API
+       documentation](https://service.greenhost.net/cloud/ApiDoc#/default) for
+       more information*
+  - In both cases you need to provide the `DOMAIN_NAME` positional argument.
+
+    If you use a subdomain (e.g. oas.yourdomain.com), use the `--subdomain`
+    command as follows: 
+
+    ```
+    $ python -m openappstack create --subdomain oas mydomain.com`.
+    ```
+
+  - Here's an example of the complete creation command: 
+
+    ```
+    python3 -m openappstack my-cluster create --create-droplet --hostname oas.mydomain.com --ssh-key-id 112 --create-domain-records --subdomain oas mydomain.com
+    ```
+
+    This will create configuration files for a cluster named `my-cluster. It
+    will also create a Greenhost VPS with the hostname `oas.mydomain.com` and on
+    which you can log in with SSH key with ID `112`. 
+
+    These DNS records will also be created by Greenhost (assuming you own the
+    domain `mydomain.com` at Greenhost):
+
+    - An `A` record `oas.mydomain.com` pointing to the VPSs IP address
+    - A `CNAME` record `*.oas.mydomain.com` pointing to `oas.mydomain.com`.
+
+2. On any other VPS
+
+   Sorry, this will be implemented ASAP! Track [this
+   issue](https://open.greenhost.net/openappstack/openappstack/issues/317)
 
 ### Installation