Merge branch '474-update-documentation' into 'master'

Resolve "Update Documentation"

Closes #474

See merge request openappstack/openappstack!207

CHANGELOG.md

@@ -4,6 +4,25 @@
 
 No unreleased changes yet.
 
+## [0.3.0] - 2019-12-24
+
+* Release candidate for beta tests
+* Added features:
+  * Single Sign on system at sso.oas.example.org
+  * User panel at admin.oas.example.org
+  * Rocket.chat version 2.1.1 at chat.oas.yourdomain
+  * Use Flux instead of Helmfile to install and update applications
+    * Flux version 1.16.0 and helm-operator version 1.0.0-rc4
+* Application updates:
+  - cert-manager 0.11.0
+  - prometheus-operator 0.34.0
+  - nginx 0.26.1
+  - nextcloud 16.0.1
+  - onlyoffice 5.4.1-2
+  - rke 0.3.2
+  - kubernetes 1.15.5
+* Fix many many bugs
+
 ## [0.2.1] - 2019-10-29
 
 This is the release for the second user test.

VERSION

-0.2.1
+0.3.0

docs/installation_instructions.md

-# OpenAppStack Tutorial
+# OpenAppStack installation instructions
 
 This document describes how you can set up a single-node OpenAppStack cluster.
 Support for multi-node clusters will come in the future.
@@ -45,9 +45,9 @@ guide][https://openappstack.net/contact.html).
 ## Install OpenAppStack command line tool
 
 On your **provisioning machine**, clone the OpenAppStack git repository and
-checkout the latest tagged version (currently `0.2.2`):
+checkout the latest tagged version (currently `0.3.0`):
 
-    $ git clone -b 0.2.2 https://open.greenhost.net/openappstack/openappstack.git
+    $ git clone -b 0.3.0 https://open.greenhost.net/openappstack/openappstack.git
     $ cd openappstack
 
 > **NOTE:** Git will display a warning after you use the `git` command
@@ -127,7 +127,7 @@ There are two options to create a cluster:
   7. Copy the generated key and run export it to this variable in a terminal:
 
      ```
-     $ export COSMOS_API_TOKEN=paste your API key here
+     $ 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) VPS, using
@@ -138,7 +138,7 @@ There are two options to create a cluster:
 
 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.
+   - Make sure to also provide the `--create-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
@@ -160,7 +160,7 @@ There are two options to create a cluster:
 - Here is an example of a 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 --create-hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org
   ```
 
   > **NOTE:** You can use the `--acme-staging` argument for testing purposes
@@ -199,7 +199,7 @@ If you want your cluster to be reachable under the fully qualified domain name
 Create the OpenAppStack settings for your VPS by running the following command:
 
 ```
-$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org
+$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
 ```
 
 ### DNS entries
@@ -257,46 +257,52 @@ sure you have the `clusters/my-cluster` directory and it contains the same
 
 When the installation is completed, you will have access to these applications:
 
+* [OAS User panel](https://open.greenhost.net/openappstack/user-panel/), our
+  user panel can be used to create and edit users. These users can be used to
+  log into the applications listed below
 * [Nextcloud](https://nextcloud.com/), a file sharing and communication
   platform;
+  - Your Nextcloud is available at https://files.oas.example.org
 * [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
-  document editing suite.
+  document editing suite;
+  - Your documents saved in Nextcloud will be opened in ONLYOFFICE
+* [Rocket.Chat](https://rocket.chat/), a team chat application;
+  - Rocket.Chat is available at https://chat.oas.example.org. Single sign-on is
+    not implemented yet for Rocket.Chat. You need to log in with the `admin`
+    user. Its password can be found in
+    `clusters/my-cluster/secrets/rocketchat_admin_password`.
 * [Grafana](https://grafana.com) that shows you information about the status of
-  your cluster. Read more about Grafana in the [monitoring chapter
-  below](#monitoring)
+  your cluster. 
+  - Read more about Grafana in the [monitoring chapter below](#monitoring)
 
-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/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.
-
-### Known limitations of Nextcloud & ONLYOFFICE
+### Known limitations
 
 - Nextcloud does not send emails yet. You can configure sending emails by going
   to Settings -> Basic settings -> Email server and entering SMTP email
   credentials.
+- Rocket.Chat does not send emails yet either
+- Rocket.Chat is not integrated with the single sign-on system. This will be
+  implemented soon in a new release.
 
 ### Monitoring
 
 You should be able to access the visual interface to the monitoring system,
-Prometheus, 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 `clusters/my-clusters/secrets/prometheus_grafana_admin_password` on
-your provisioning machine.
+Prometheus, at `https://grafana.oas.example.org/`. Admin users can log into
+Grafana. You can create and add admin users through the User panel.
 
 ### Other applications installed into the cluster
 
 Besides these applications, some other auxiliary components are installed:
 
-* `local-storage` provides an easy way for the cluster to use a directory on
+* [OAS local-storage](https://open.greenhost.net/openappstack/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,
+* [NGINX](https://www.nginx.com) is a webserver that functions as a so-called ingress controller,
   routing web traffic that enters the cluster to the various applications;
-* `cert-manager` acquires and stores [Let's Encrypt](https://letsencrypt.org/)
-  certificates, enabling encrypted web traffic to all applications running in
-  the cluster;
+* [cert-manager](https://cert-manager.io) acquires and stores [Let's
+  Encrypt](https://letsencrypt.org/) certificates, enabling encrypted web
+  traffic to all applications running in the cluster;
+* [Flux](https://fluxcd.io) checks for application updates approved by the
+  OpenAppStack team and installs them automatically.
 
 ## Managing an existing cluster
 

docs/reference.md

@@ -5,10 +5,6 @@
 During the installation process, the following files and directories are
 created:
 
-- `/etc/OpenAppStack`: directory containing all configuration files that you
-  may want to review and edit during normal usage. See the `README.md` file
-  inside this directory for more details.
-
 - `/var/lib/OpenAppStack/local-storage`: all application data (e.g., Nextcloud
   files) are stored here.
 

docs/testing_instructions.md

@@ -8,6 +8,9 @@ At any point please feel invited to test whatever functionality you come across,
 think is interesting. Our contact details are listed [here](https://openappstack.net/contact.html), and we'll
 descibe how to give feedback via our issue tracker at the [end of these instructions](#providing-feedback).
 
+During these instructions, please replace *example.org* with your own domain
+name.
+
 ## Installation
 
 First we'd like you to setup an OpenAppStack cluster by yourself, following the
@@ -18,16 +21,26 @@ First we'd like you to setup an OpenAppStack cluster by yourself, following the
 Please run the [command line tests](troubleshooting.md) which checks the overall
 functionality of your cluster and include the output in your feedback.
 
-## Nextcloud
+## User panel
 
-### Logging into Nextcloud
+Please open https://admin.oas.example.org in the browser. You should see
+"Welcome to OpenAppStack" and a Login button. Please try logging in.
+
+An admin user was generated with the username `admin`. The password is saved in
+`clusters/my-cluster/secrets/userbackend_admin_password` in the OpenAppStack
+directory on your local machine.
+
+After logging in to the user panel, please try to make a new user. Don't forget
+to give it a username and password, and press "Save" afterwards.
 
-Please browse to https://files.$YOURPUBLICDOMAIN and try to log in.
-  The username is `admin`. The password was generated as part of the installation process and is stored in the file `clusters/CLUSTER_NAME/secrets/nextcloud_admin_password` in the `openappstack` directory of your provisioning machine (the cluster_data folder was created in the directory where you ran Ansible during the tutorial).
+## Nextcloud
 
-### Creating users
+### Logging into Nextcloud
 
-* After logging in to Nextcloud as `admin`, please try to create another Nextcloud user. Ideally, you would create accounts for a few of your coworkers who are willing to try the collaboration features of Nextcloud and OnlyOffice with you.
+Please browse to https://files.oas.example.org and try to log in. You should
+have a buttin saying "Login with OpenAppStack". Try that button. Please try
+logging in with your admin account, as well as the user you created in the user
+panel.
 
 ### Nextcloud client application
 
@@ -35,19 +48,28 @@ Please browse to https://files.$YOURPUBLICDOMAIN and try to log in.
 * If you feel like it, please try the [Nextcloud mobile client](https://nextcloud.com/clients/) for your smartphone, connect it to your OpenAppStack instance, and use it to download and/or open some files, upload a new file, etc.
 
 
-## OnlyOffice
+## ONLYOFFICE
 
 ### Creating a new office document
 
-* From the main Nextcloud webpage, please try to create a new office document, by clicking the round `plus` button near the top of the screen, then picking the `Document` type with the blue icon (third one from below on my screen), and enter a name for it. After that, please try some basic editing of the document, and save it. Maybe check you can open it again afterwards, and that it has the contents that you saved earlier.
-
+From the main Nextcloud webpage, please try to create a new office document, by clicking the round `plus` button near the top of the screen, then picking the `Document` type with the blue icon (third one from below on my screen), and enter a name for it. After that, please try some basic editing of the document, and save it. Maybe check you can open it again afterwards, and that it has the contents that you saved earlier.
 
 ### Collaborating on an office document
 
 This part of the test requires the cooperation of another person; feel free to skip it now if that's not convenient at this point.
 
-* Please try to open the same office document from a few different user accounts simultaneously, and let all participants edit the document mercilessly. There are also some collaboration features that you may want to try: on the left of the OnlyOffice screen there are buttons for chat and for text comments.
+* First, try to share your document with a different user.
+* Then, try to open the shared document from a few different user accounts simultaneously, and let all participants edit the document mercilessly. There are also some collaboration features that you may want to try: on the left of the OnlyOffice screen there are buttons for chat and for text comments.
+
+## Rocket.Chat
+
+You can find Rocket.Chat at https://chat.oas.example.org. Please go there and
+try to log in.
 
+Note that at the moment we have not integrated Rocket.Chat with the single
+sign-on system yet. You can only sign in with the automatically created
+administrator account. The username is `admin` and the password can be found in
+`clusters/my-cluster/secrets/rocketchat_admin_password`
 
 ## Providing feedback
 

docs/troubleshooting.md

@@ -43,9 +43,9 @@ and running and correctly connected to each other. They are integrated in the
 
 #### Prerequisites
 
-By default the behave tests use the Chrome/Chromium webdriver.  If you want/need
-to use the Firefox webdriver please refer to the manual behave test instructions
-below, under `Advanced Usage`.
+By default the behave tests use the Chromium browser and Chromium webdriver. If
+you want/need to use the Firefox webdriver please refer to the manual behave
+test instructions below, under [Advanced Usage](#advanced-usage).
 
 Install [Chromedriver](https://sites.google.com/a/chromium.org/chromedriver/),
 i.e. for Debian/Ubuntu use:
@@ -106,25 +106,30 @@ then:
 
 #### Behave tests
 
-Change to the `test/behave` directory and run:
+##### Using Firefox instead of Chromium 
 
-For nextcloud test:
+If you want to use Firefox instead of Chromium, you need to install the gecko
+driver
 
-    behave -D nextcloud.url=https://files.example.openappstack.net \
-           -D nextcloud.password="$(cat ../../clusters/YOUR_CLUSTERNAME/secrets/nextcloud_admin_password)" \
-           -t nextcloud
+    apt install firefox-geckodriver
 
-For grafana test:
+Now you only need to add `-D browser=firefox` to the behave command line
+options, so run:
 
-    behave -D grafana.url=https://grafana.example.openappstack.net \
-           -D grafana.password="$(cat ../../clusters/YOUR_CLUSTERNAME/secrets/grafana_admin_password)" \
-           -t grafana
+    python -m openappstack CLUSTER_NAME test --behave-param='-D browser=firefox'
 
-Use Firefox instead of Chromium:
+##### Using behave without the OpenAppStack CLI
 
-    apt install firefox-geckodriver
+Go to the `test/behave` directory and run:
+
+For nextcloud & onlyoffice tests:
+
+    behave -D nextcloud.url=https://files.example.openappstack.net \
+           -D nextcloud.password="$(cat ../../clusters/YOUR_CLUSTERNAME/secrets/nextcloud_admin_password)" \
+           -t nextcloud
 
-Now you only need to add `-D browser=firefox` to the behave command line options.
+You can replace `nextcloud` with `grafana` or `rocketchat` to test the other
+applications.
 
 #### Run behave tests in openappstack-ci docker image
 

docs/upgrading.md

 # Upgrading OpenAppStack
 
-## From versions earlier than 0.2.3
+## From versions earlier than 0.3.0
 
-Upgrading from versions earlier than `0.2.3` requires manual
+Upgrading from versions earlier than `0.3.0` requires manual
 intervention.
 
 * Move your local `settings.yml` file to a different location:
@@ -13,6 +13,17 @@ intervention.
     mv settings.yml ./group_vars/all/
     ```
 
-* remove all helm charts (WARNING: Please backup all data before!):
+* [Flux](https://fluxcd.io) is now used to install and update applications. For
+  that reason, we need you to remove all helm charts (WARNING: You will lose
+  your data!): 
+
+  ```
+  helm delete --purge oas-test-cert-manager oas-test-local-storage \
+      oas-test-prometheus oas-test-proxy oas-test-files`
+  ```
+  - After removing all helm charts, you probably also want to remove all the
+    `pvc`s that are left behind. Flux will not re-use the database PVCs created
+    for these applications. Find all the pvcs by running `kubectl get pvc
+    --namespace oas-apps` and `kubectl get pvc --namespace oas`
+
 
-    `helm delete --purge oas-test-cert-manager oas-test-local-storage oas-test-prometheus oas-test-proxy oas-test-files`