diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 0949d2884f51f029dba58c1d6791fd804863c3f6..0000000000000000000000000000000000000000 --- a/docs/usage.md +++ /dev/null @@ -1,117 +0,0 @@ -# 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/oas.example.org/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 follow the [user panel documentation](https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user) -to create a new user. - -*Note*: 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. - -You can now use the new user to log in 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 can open documents in Onlyoffice by clicking them in Nextcloud. You can open new documents by clicking the "Plus" button in Nextcloud and selecting Document, Spreadsheet or Presentation. - - -### Rocketchat - -[Rocketchat](https://rocket.chat/) is a team chat application and available at -https://chat.oas.example.org. - -### Known issues - -- [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 log in without single 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 log in without signgle sign-on using the -`grafana_admin_password` password in the `secrets` folder. - - -### Other applications installed into the cluster - -Besides these applications, some other components are installed. -These are part of the OpenAppStack back end and they dont't have a user facing -web interfaces, but we like to list them here for reference: - -* [rancher's local-path-provisioner](https://github.com/rancher/local-path-provisioner) 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. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000000000000000000000000000000000000..299bcdd4608b9bbe27d6adb697e54e1b25862456 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,104 @@ +Usage +===== + +After all the applications are installed, the first thing to do is log into +https://admin.oas.example.org. This is 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 by running + +.. code:: bash + + python3 -m openappstack oas.example.org secrets + +Search for ``userbackend_admin_password``. + +After logging in, you will see an overview of all the installed 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:: + + If you don't see applications, make sure you have installed at least one + optional application in :ref:`step-5` of the installation procedure. + +Core 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 follow the [user panel documentation](https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user) +to create a new user. + +*Note*: 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. + +You can now use the new user to log in to all apps which were granted access to +in the last step using single sign-on. + +Grafana +~~~~~~~ + +`Grafana <https://grafana.com>`__ is a dashboard application that shows you +information about the status of your cluster collected by `Prometheus +<https://prometheus.io>`__. Grafana is available at +https://grafana.oas.example.org. + +Single sign-on users +'''''''''''''''''''' + +Users that have the "Admin" label turned on in the user panel, will have admin +rights in Grafana. Other users are able to see graphs, but can not change +anything. + +Optional applications +--------------------- + +Nextcloud +~~~~~~~~~ + +`Nextcloud <https://nextcloud.com/>`__ is a file sharing and communication +platform and is available at https://files.oas.example.org. + +Onlyoffice +~~~~~~~~~~ + +`Onlyoffice <https://www.onlyoffice.com/connectors-nextcloud.aspx>`__ is an +online document editing suite. Your can open documents in Onlyoffice by clicking +them in Nextcloud. You can open new documents by clicking the "Plus" button in +Nextcloud and selecting Document, Spreadsheet or Presentation. + +.. warning:: + + OpenAppStack has a known issue that can cause loss of ONLYOFFICE + documents when the machine gets restarted or loses access to its disk. + + Track the following issue to see if it is solved: https://open.greenhost.net/openappstack/nextcloud/-/issues/967 + + We are working hard to resolve the issue. + +RocketChat +~~~~~~~~~~ + +`RocketChat <https://rocket.chat/>`__ is a team chat application and available +at https://chat.oas.example.org. + + +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.