improve installation instructions based on our own feedback in #309 and #326

docs/installation_instructions.md

@@ -74,7 +74,8 @@ Now you can run the OpenAppStack CLI as follows:
 
 The CLI *always* needs a `CLUSTER_NAME` argument. Even for getting subcommand
 help messages. Be sure to run this command in the root directory of the git
-repository. Try it out by running
+repository. In this tutorial, we're using `my-cluster` as the cluster name. Try
+it out by running
 
     $ python -m openappstack my-cluster --help
 
@@ -100,12 +101,10 @@ Setting up OpenAppStack on your VPS happens in three steps:
 ### Set up cluster
 
 To set up your cluster, use the `create` subcommand of the OpenAppStack CLI.
-First, choose a name for your cluster. Then run the following command to get
+First, choose a name (we chose `my-cluster`) 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 your chosen name.
+    $ python -m openappstack my-cluster create --help
 
 There are two options to create a cluster:
 
@@ -118,18 +117,18 @@ There are two options to create a cluster:
   4. Click "New API key"
   5. Click "Generate new key"
   6. Give the key "Customer", "CloudCustomer" or "API" access rights. You will
-     need "Customer" rights if you want to automatically generate DNS rules.
-     If you do not have this right, you have to manually set the right DNS
-     rules.
+     need "Customer" rights if you want to automatically generate DNS rules. If
+     you do not have this right, you have to [manually set the right DNS
+     rules](http://docs.openappstack.net/en/latest/installation_instructions.html#dns-entries)
+     later.
   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.
+1. Based on an already existing [Greenhost](https://greenhost.net) VPS, using
+   the `--droplet-id` argument.
 
    Find the ID of your VPS either in the Greenhost Cosmos interface
    (it is the numeric part of the URL in the "Manage VPS" screen).
@@ -142,10 +141,8 @@ There are two options to create a cluster:
      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
+     *Note: You can also use the API to list ssh keys and find it there. Read
+     the [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.
@@ -154,15 +151,19 @@ There are two options to create a cluster:
   command as follows:
 
   ```
-  $ python -m openappstack create --subdomain oas example.org`.
+  $ python -m openappstack my-cluster create --subdomain oas example.org
   ```
 
 - Here is an example of the complete creation command:
 
   ```
-  python -m openappstack my-cluster create --create-droplet --hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org
+  python -m openappstack my-cluster create --create-droplet --hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org --acme-live-environment
   ```
 
+  > **NOTE:** We use the `--acme-live-environment` argument. This ensures you
+  > get real (instead of "staging") Let's Encrypt TLS certificates. This is
+  > necessary for ONLYOFFICE integration to work.
+
   This will create configuration files for a cluster named `my-cluster`. It
   will also create a Greenhost VPS with the hostname `oas.example.org` and on
   which you can log in with SSH key with ID `112`.
@@ -186,9 +187,13 @@ its *hostname* and its *IP address*. Also check that your VPS meets our
 Create the OpenAppStack settings for your VPS by running the following command:
 
 ```
-$ python -m openappstack create --ip-address IP_ADDRESS --hostname HOSTNAME --subdomain oas example.org
+$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --hostname HOSTNAME --subdomain oas example.org --acme-live-environment
 ```
 
+> **NOTE:** We use the `--acme-live-environment` argument. This ensures you get
+> real (instead of "staging") Let's Encrypt TLS certificates. This is necessary
+> for ONLYOFFICE integration to work.
+
 ### DNS entries
 
 Before you continue, if you have not made DNS entries with the CLI tool, you
@@ -229,7 +234,7 @@ To start the installation process, run:
 
     $ python -m openappstack my-cluster install
 
-This will take approximately 5-10 minutes. It generates secrets that will be
+This will take between 5 and 20 minutes. It generates secrets that will be
 added to the `clusters/my-cluster/secrets` directory. If you ever need any
 credentials after this installation, you can probably find them there. **Make
 sure this directory stays safe.** Feel free to encrypt it when you are not using
@@ -254,7 +259,7 @@ When the installation is completed, you will have access to these applications:
 
 You can access Nextcloud via https://files.example.org. Use the username
 `admin` with the automatically generated Nextcloud password that you can find in
-`clusters/maarten/secrets/nextcloud_admin_password` on your local machine.
+`clusters/my-cluster/secrets/nextcloud_admin_password` 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.