Move Usage docs to own document, improve app section

docs/index.rst

@@ -27,9 +27,10 @@ For more information, go to `the OpenAppStack website`_.
    :caption: Contents:
 
    installation_instructions
-   upgrading
    testing_instructions
+   usage
    troubleshooting
    maintenance
+   upgrading
    design
    reference

docs/installation_instructions.md

@@ -207,7 +207,7 @@ meets our [prerequisites](#prerequisites).  You'll need its *hostname* and its
 > you are automating this, please use this to ensure you use "staging"
 > certificates from Let's Encrypt, to reduce the stress on their servers.
 > However, ONLYOFFICE and single sign-on integration require valid (live)
-> certificates to work properly so please don't use this option by default. 
+> certificates to work properly so please don't use this option by default.
 
 If you want your cluster to be reachable under the fully qualified domain name
 (`FQDN`) `oas.example.org`, the corresponding parameters would be:
@@ -289,81 +289,3 @@ continue to the Usage section.
 Because OpenAppStack is still under development, we would like you to follow our
 [testing instructions](testing_instructions) to make sure that the setup process
 went well.
-
-## Usage
-
-After all the applications are installed, the first thing to do is log into
-https://admin.oas.example.org. Here you can find the "user panel", a place where
-you can create, edit and delete users. You can log in with the user "admin". The
-password can be found in
-`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
-will see an overview of all the applications your user has access to. For more
-information on how to create users and give them access to applications, take a
-look at the [user panel
-documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
-
-> **NOTE:** at the moment none of the applications are available at
-> `oas.example.org`, we only provide applications in subdomains. In the future
-> this might change.
-
-These applications should be available after the installation is completed:
-
-* [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;
-  - 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`.
-* [WordPress](https://wordpress.com), a website content management system.
-  - WordPress is available at https://www.oas.example.org. Click the "Log in"
-    button and then click "Login with OpenID Connect" to use the single sign-on
-    server. Note that if you log in with the single sign-on server, you will not
-    have "admin" rights within WordPress. For that, use the admin credentials in
-    the `secrets` folder.
-* [Grafana](https://grafana.com) that shows you information about the status of
-  your cluster.
-  - Read more about Grafana in the [monitoring chapter below](#monitoring)
-
-### Known limitations
-
-- Single sign-on is still in an experimental phase. We are still working on
-  transferring "roles" from users in the central database to applications, so
-  your SSO's admin user gets admin permissions in all the applications.
-  - This means that if you need to login as an Admin user, you need to use the
-    admin credentials in `clusters/my-cluster/secrets/<app_admin_password>`.
-  - To use single sign-on with Grafana, your user *needs* to have an email
-    address set in the user database.
-- 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/`. 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:
-
-* [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](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](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.

docs/usage.md

+# Usage
+
+After all the applications are installed, the first thing to do is log into
+https://admin.oas.example.org. Here you can find the "user panel", a place where
+you can create, edit and delete users. You can log in with the user "admin". The
+password can be found in
+`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
+will see an overview of all the applications your user has access to. For more
+information on how to create users and give them access to applications, take a
+look at the [user panel
+documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
+
+> **NOTE:** at the moment none of the applications are available at
+> `oas.example.org`, we only provide applications in subdomains. In the future
+> this might change.
+
+## Applications
+
+These applications are available after the installation is completed
+successfully:
+
+
+### OAS User panel
+
+The [OAS user panel](https://open.greenhost.net/openappstack/user-panel/)
+can be used to create and edit users. These users can be used to log into the
+applications listed below.
+The user panel is available at https://admin.oas.example.org. You can login
+as `admin` using the `userbackend_admin_password` password from your secrets
+folder.
+
+After logging in to the user panel, please create a new user:
+* Click on `Users` in the upper left corner
+* Click on `Add user`
+* Enter username and click `Submit`
+* Provide the password and email address. The email address is important
+  because some applications need a valid email address for notification mails.
+  Single sign-on with Grafana will fail for users lacking an email address.
+* Click on `Add app` and enter the name of the app the new user should get
+  access to, and click on `Add`. Repeat for all other apps.
+* Click on `Save` to finsish.
+
+You can now use the new user to login to all apps which were granted access to
+in the last step using single sign-on.
+
+
+### Nextcloud
+
+[Nextcloud](https://nextcloud.com/) is a file sharing and communication
+platform and is available at https://files.oas.example.org.
+
+#### Single sign-on
+
+Nextcloud needs to be configured to properly send out emails.
+You can do so by logging in as `admin` using signle sign-on and then going to
+`Settings -> Basic settings -> Email server` and entering your SMTP email
+config and credentials.
+Please complete this configuration before you login as non-admin user using
+single sign-on, otherwise the [first login will not succeed](https://open.greenhost.net/openappstack/openappstack/issues/508).
+
+
+### Onlyoffice
+
+[Onlyoffice](https://www.onlyoffice.com/connectors-nextcloud.aspx) is an online
+document editing suite. Your documents saved in Nextcloud will be opened in
+Onlyoffice.
+
+
+### Rocketchat
+
+[Rocketchat](https://rocket.chat/) is a team chat application and available at
+https://chat.oas.example.org.
+In order to activate single sign-on you need to follow these steps once:
+
+- Log in as `admin` using the `rocketchat_admin_password` from your secrets
+  folder.
+- On the top left side click on the `Options` button (three dots) and then click
+  on `Administration`
+- In the left menu scroll down and click on `OAuth` (not `oauth apps`)
+- Click on `add custom oauth` and enter `Openappstack`
+- Click on the newly added `Custom OAuth: Openappstack` provider
+- Change the following settings (leave all others like they are):
+  - Enable: `True`
+  - URL: `https://sso.oas.example.org`
+  - Token Path: `/oauth2/token`
+  - Identity Path: `/userinfo`
+  - Authorize Path: `/oauth2/auth`
+  - Scope: `openid profile openappstack_roles email`
+  - Id: `rocketchat`
+  - Secret: Paste the `rocketchat_oauth_client_secret` from your secrets folder
+  - Login Style: `Redirect`
+  - Button Text: `Login with OpenAppStack`
+  - Username field: `preferred_username`
+  - Name files: `name`
+  - Roles/Groups field name: `openappstack_roles`
+  - Merge roles from SSO: `True`
+  - Merge users: `True`
+- Click `Save changes`, log out and you are done.
+
+Next time you login to Rocketchat you will be able to use single sign-on using
+the `Login` button.
+
+#### Single sign-on
+
+- [Rocketchat isn't configured yet to send out email notifications](https://open.greenhost.net/openappstack/openappstack/issues/510)
+
+
+### Wordpress
+
+[Wordpress](https://wordpress.com) is a website content management system and
+available at https://www.oas.example.org.
+Click the `Log in` button and then click `Login with OpenID Connect` to use
+single sign-on.
+
+#### Single sign-on
+
+- If you [log in as `admin` using single sign-on, you will not have
+admin rights within Wordpress](https://open.greenhost.net/openappstack/single-sign-on/issues/33).
+In order to use admin rights you need to login without signgle sign-on using the
+`wordpress_admin_password` password in the `secrets` folder.
+
+
+### Grafana
+
+[Grafana](https://grafana.com) that shows you information about the status of
+your cluster.
+Read more about Grafana in the [monitoring chapter below](#monitoring)
+
+#### Single sign-on
+
+- If you [log in as `admin` using single sign-on, you will not have
+admin rights within Grafana](https://open.greenhost.net/openappstack/single-sign-on/issues/32).
+In order to use admin rights you need to login without signgle sign-on using the
+`grafana_admin_password` password in the `secrets` folder.
+
+
+### Known issues
+
+- Single sign-on is still in an experimental phase. We are still working on
+  transferring "roles" from users in the central database to applications, so
+  your SSO's admin user gets admin permissions in some of the applications.
+  Please see the application specific notes about single sign-on in the `Usage`
+  documentation for details.
+
+
+### Monitoring
+
+You should be able to access the visual interface to the monitoring system,
+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:
+
+* [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](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](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.