diff --git a/docs/installation_instructions.md b/docs/installation_instructions.md
index 408ce6882c7a985c4e127cd86a81ab0764e9ed44..3c2fe79613312a2696aef441bc4caad338714d0a 100644
--- a/docs/installation_instructions.md
+++ b/docs/installation_instructions.md
@@ -1,20 +1,24 @@
# OpenAppStack Tutorial
-Here's how you can set up a single-node OpenAppStack cluster. Support for
-multi-node clusters will come in the future.
+This document describes 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.**
+> **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.
+
+If you encounter any difficulties while following these instructions, please
+open an issue on:
+[open.greenhost.net/openappstack/openappstack][https://open.greenhost.net/openappstack/openappstack).
## Warnings
-* OpenAppStack is still under heavy development, and is not ready for
+* OpenAppStack is still under heavy development and is not ready for
production use! We anticipate major changes and do not guarantee a
- data-preserving upgrade path from current installations. Feel free to try
- OpenAppStack for testing though, and please
- [report](https://openappstack.net/contact.html) any issues you encounter.
+ data-preserving upgrade path from current installations. However, we encourage
+ you to try OpenAppStack and ask you to
+ [report all issues you encounter](https://openappstack.net/contact.html).
* When you install OpenAppStack on a server, the installation process will make
some substantial changes to the server's configuration, so please do not use
a server that functions as anything other than a testing ground.
@@ -24,14 +28,14 @@ machine.**
* A virtual machine or bare metal server with:
* current Debian stable "buster";
* a public IP address;
- * 8GB of RAM;
+ * 6GB of RAM;
* 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`
+ * You need Python 3 and [virtualenv](https://virtualenv.pypa.io/en/stable/) to
+ make sure we do not change any of your other projects. Install virtualenv
+ by running `pip3 install --user virtualenv` or `apt install virtualenv`
## Install OpenAppStack command line tool
@@ -42,22 +46,31 @@ On your **local machine**, clone the OpenAppStack git repository:
Next, install the OpenAppStack CLI client by running the following commands:
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.
+makes sure we do not change any of your other python projects. The second command
+"activates" the virtualenv.
+
+> **NOTE:** Activating the virtualenv means you will use that environment to
+> install and run python programs instead of your global environment. If you
+> close your terminal or open a new one, you need to activate the virtualenv
+> again.
$ virtualenv env -p python3
$ . env/bin/activate # activate the virtual environment
$ pip install -r requirements.txt
-*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.*
+> *Hint:* if the `pip install` command results in a [segmentation
+> fault](https://bitbucket.org/cffi/cffi/issues/272/segfault-while-installing-via-pip),
+> you can add `--no-use-wheel` to it.
Now you can run the OpenAppStack CLI as follows:
- $ python -m openappstack CLUSTER_NAME
+ $ python -m openappstack CLUSTER_NAME <command>
The CLI *always* needs a `CLUSTER_NAME` argument. Even for getting subcommand
-help messages.
+help messages. Be sure to run this command in the root directory of the git
+repository. Try it out by running
+
+ $ python -m openappstack my-cluster --help
## Install OpenAppStack
@@ -95,9 +108,9 @@ There are two options to create a cluster:
3. Click "API keys"
4. Click "New API key"
5. Click "Generate new key"
- 6. Give the key "Customer", "CloudCustomer" or "API" access rights. You'll
+ 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 don't have this right, you have to manually set the right DNS
+ If you do not have this right, you have to manually set the right DNS
rules.
7. Copy the generated key and run export it to this variable in a terminal:
@@ -110,7 +123,7 @@ There are two options to create a cluster:
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).
+ (it is 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
@@ -135,7 +148,7 @@ There are two options to create a cluster:
$ python -m openappstack create --subdomain oas example.org`.
```
- - Here's an example of the complete creation command:
+ - 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
@@ -158,25 +171,22 @@ There are two options to create a cluster:
#### DNS entries
-Before you continue, if you haven't made DNS entries with the CLI tool, make them yourself.
-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 (sub)domain entry and a
-wild card entry for everything inside it. For example, create an A record for
-these domains:
+Before you continue, if you have not made DNS entries with the CLI tool, you
+need to make them now. It is important to start with configuring DNS because
+depending on your DNS setup/provider, it takes a while (sometimes hours) to
+propagate. You need one dedicated (sub)domain entry and a wild card entry for
+everything inside it. For example, create these two records for your domain:
-- oas.example.org
-- \*.oas.example.org
+- An `A` record `oas.example.org` pointing to the VPSs IP address
+- A `CNAME` record `*.oas.example.org` pointing to `oas.example.org`.
-And make them point to your VPS's public IP address.
-Make sure your DNS is propagated before continuing to the installation step. To
-do so, use `ping`:
-
- $ ping oas.example.org
+### Installation
-Make sure this shows your VPS's IP before you continue.
+Before you start the installation, make sure your DNS is propagated. To do so,
+make sure 'ping' shows your VPS's IP address:
-### Installation
+ $ ping oas.example.org
The installation process sets up a single-node Kubernetes cluster on the machine
and installs the utility tools `helmfile`, `helm`, `kubectl` and `rke`.
@@ -186,12 +196,15 @@ 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
-added to the clusters/my-cluster/secrets directory. If you ever need any credentials after
-this installation, find the passwords there. **Make sure this directory stays
-safe.** Feel free to encrypt it when you're not using the `openappstack` CLI tool.
+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
+the `openappstack` CLI tool.
You can re-run the `install` command. Make sure you re-run it on a machine with
-the same `secrets` as generated the first time.
+the same `secrets` as generated the first time. You can achieve this by making
+sure you have the `clusters/my-cluster` directory and it contains the same
+`secrets` directory before you run the installation command.
## Usage
@@ -201,17 +214,22 @@ When the installation is completed, you will have access to these applications:
platform;
* [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
document editing suite.
+* [Grafana](https://grafana.com) that shows you information about the status of
+ your cluster. Read more about Grafana in the [monitoring chapter
+ below](#monitoring)
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
`clusters/maarten/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.
+https://office.oas.example.org.
### Known limitations of Nextcloud & ONLYOFFICE
-- Nextcloud does not send emails yet.
+- Nextcloud does not send emails yet. You can configure sending emails by going
+ to Settings -> Basic settings -> Email server and entering SMTP email
+ credentials.
### Monitoring
@@ -236,7 +254,7 @@ Besides these applications, some other auxiliary components are installed:
## Managing an existing cluster
You can use `kubectl`, the Kubernetes control program, to find and manipulate
-your Kubernetes cluster. Once you've installed `kubectl`, to get access to your
+your Kubernetes cluster. Once you have installed `kubectl`, to get access to your
cluster with the OAS CLI:
$ python -m openappstack my-cluster info
@@ -248,13 +266,14 @@ Look for these lines:
export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
Copy the whole `export` line into your terminal. In *that* terminal, kubectl
-will connect to your cluster. **NOTE:** you have to repeat this step in other
-terminals and tabs.
+will connect to your cluster.
+
+> **NOTE:** you have to repeat this step in new terminals and terminal tabs.
### SSH access
Alternatively, you can SSH login to your VPS. Some programs that are
-available on the VPS:
+available to the root user on the VPS:
* `kubectl`, the Kubernetes control program. The root user is connected to the
cluster automatically.