Update documentation based on first user feedback

Closes: #303

docs/installation_instructions.md

@@ -4,9 +4,9 @@ Here's how you can set up a single-node OpenAppStack cluster. Support for
 multi-node clusters will come in the future.
 
 **NOTE: All commands in these installation instructions need to be run on a
-trusted machine that is *not* the VPS that will run OpenAppStack. The
-installation process will generate some secrets that will be saved to this
-machine.**
+trusted provisioning machine (i.e. your laptop) that is *not* the VPS that will
+run OpenAppStack. The installation process will generate some secrets that will
+be saved to this machine.**
 
 ## Warnings
 
@@ -31,14 +31,22 @@ machine.**
 
 ### 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
-wildcard entry for everything inside it. For example, create an A record for
-these domains:
+OpenAppStack will fetch https certificated with [Let's Encrypt](https://letsencrypt.org)
+by default. In order to do this DNS entries need to get created.
+If you don't need https certificates for your cluster while testing you can skip
+this step. Please be aware of the limitations of this:
 
-- oas.example.org
-- \*.oas.example.org
+* Onlyoffice won't work since it requires a valid certificate connecting to nextcloud.
+* You need to be able to resolve the domain names locally.
+
+It's important to start with configuring DNS first because depending on your DNS
+setup/provider, it takes a while to propagate.
+
+You need one dedicated subdomain entry and a wildcard entry for everything
+inside it. For example, create an A record for these domains:
+
+- `example.org`
+- `*.example.org`
 
 and make them point to your machine's public IP address.
 
@@ -47,16 +55,30 @@ and make them point to your machine's public IP address.
 On your **local machine**, clone the OAS bootstrap repo:
 
     $ git clone https://open.greenhost.net/openappstack/openappstack.git
+    $ cd openappstack
+
+Copy the example ansible inventory and settings file to your cluster directory:
+
+    $ mkdir clusters/YOUR_CLUSTER_NAME
+    $ cp ansible/inventory.yml.example clusters/YOUR_CLUSTER_NAME/inventory.yml`
+    $ cp ansible/group_vars/all/settings.yml.example clusters/YOUR_CLUSTER_NAME/settings.yml
+
+Then edit both files and changes values according to your new cluster.
+For `inventory.yml`:
+
+* Change all appearances of `oas-dev` to match `YOUR_CLUSTER_NAME`.
+* Change `ansible_host` to match the IP of your cluster.
 
-Copy `ansible/inventory.yml.example` to `ansible/inventory.yml` and edit it to
-reflect your cluster.
+For `settings.yml`:
 
-Also copy `ansible/group_vars/all/settings.yml.example` to
-`ansible/group_vars/all/settings.yml` and edit as you see fit.
+* `ip_address`: The IP of your cluster.
+* `domain`: The main domain of your cluster.
+  Corresponding to the example DNS entries this would be `example.org`.
+* `admin_email`: The email address where system mails should be sent to.
 
-### Prerequisites
+### Ansible
 
-* You need `ansible >= 2.7` installed on your workstation to run the bootstrap
+* You need `ansible >= 2.7` installed on your provisioning machine to run the bootstrap
   scripts. Please install it using your system package manager.
 
   In the case your system package manager doesn't provide that particular
@@ -98,12 +120,12 @@ Right now, these end user applications are installed:
 * [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
   document editing suite.
 
-You can access Nextcloud via https://files.oas.example.org. Use the username
+You can access Nextcloud via https://files.example.org. Use the username
 `admin` with the automatically generated Nextcloud password that you can find in
 the `ansible/cluster_data/secrets/` folder on your local machine.  ONLYOFFICE is
 already integrated in your Nextcloud installation which allows you to create and
 share ONLYOFFICE documents within Nextcloud. ONLYOFFICE runs on
-https://office.oas.example.org.
+https://office.example.org.
 
 Besides these applications, some other auxiliary components are installed:
 
@@ -120,16 +142,16 @@ Besides these applications, some other auxiliary components are installed:
 ### Monitoring
 
 You should be able to access the visual interface to the monitoring system at
-`https://grafana.oas.example.org/`. A user `admin` is created at installation
+`https://grafana.example.org/`. A user `admin` is created at installation
 time; the password that was generated during installation is stored in the file
 `ansible/cluster_data/secrets/prometheus_grafana_admin_password` on your
-workstation.
+provisioning machine.
 
 ## Managing an existing cluster
 
 Log in to your cluster with:
 
-    $ ssh USER@oas.example.org
+    $ ssh USER@example.org
 
 where `USER` is the `ansible_user` you configured in `ansible/inventory.yml`.