From 7d1911a7d0db6f3c38f9a2d714bbeb1344a716fb Mon Sep 17 00:00:00 2001
From: Maarten de Waard <maarten@greenhost.nl>
Date: Thu, 1 Aug 2019 10:53:44 +0200
Subject: [PATCH] improve tutorial: clarify you need to run commands locally,
 add onlyoffice url

---
 docs/installation_instructions.md | 37 +++++++++++++++++++------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/docs/installation_instructions.md b/docs/installation_instructions.md
index 6e2935291..0ffdb588a 100644
--- a/docs/installation_instructions.md
+++ b/docs/installation_instructions.md
@@ -3,6 +3,11 @@
 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.**
+
 ## Warnings
 
 * OpenAppStack is still under heavy development, and is not ready for
@@ -17,7 +22,6 @@ multi-node clusters will come in the future.
 ## Prerequisites
 
 * A virtual machine or bare metal server with:
-
   * current Debian stable "buster";
   * a public IP address;
   * 8GB of RAM;
@@ -40,9 +44,9 @@ and make them point to your machine's public IP address.
 
 ## Configure your cluster
 
-Clone the OAS bootstrap repo:
+On your **local machine**, clone the OAS bootstrap repo:
 
-    git clone https://open.greenhost.net/openappstack/openappstack.git
+    $ 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.
@@ -79,7 +83,7 @@ To run the bootstrap process, you need to move into the `ansible/` directory,
 then run
 
 ```
-ansible-playbook bootstrap.yml
+$ ansible-playbook bootstrap.yml
 ```
 
 It will take approximately 5 to 10 minutes to set up your cluster. Please
@@ -87,18 +91,22 @@ It will take approximately 5 to 10 minutes to set up your cluster. Please
 
 ## Usage
 
-Right now, there are two applications installed:
-* [Nextcloud](https://nextcloud.com/), a file sharing and communication platform;
-* [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online document
-  editing suite.
+Right now, these end user applications are installed:
+
+* [Nextcloud](https://nextcloud.com/), a file sharing and communication
+  platform;
+* [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
-`admin` with the automatically generated Nextcloud password that you can find in the `ansible/cluster_data/secrets/`
-folder on your workstation.
-ONLYOFFICE is already integrated in your Nextcloud installation which allows you to create and
-share ONLYOFFICE documents within Nextcloud.
+`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.
 
 Besides these applications, some other auxiliary components are installed:
+
 * `local-storage` provides an easy way for the cluster to use a directory on
   the node (by default `/var/lib/OpenAppStack/local-storage`) for storage;
 * nginx is a webserver that functions as a so-called ingress controller,
@@ -114,13 +122,14 @@ Besides these applications, some other auxiliary components are installed:
 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
 time; the password that was generated during installation is stored in the file
-`ansible/cluster_data/secrets/prometheus_grafana_admin_password` on your workstation.
+`ansible/cluster_data/secrets/prometheus_grafana_admin_password` on your
+workstation.
 
 ## Managing an existing cluster
 
 Log in to your cluster with:
 
-    ssh USER@oas.example.org
+    $ ssh USER@oas.example.org
 
 where `USER` is the `ansible_user` you configured in `ansible/inventory.yml`.
 
-- 
GitLab