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.

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 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 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.

Onlyoffice

Onlyoffice 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 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

Wordpress

Wordpress 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. 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 that shows you information about the status of your cluster. Read more about Grafana in the monitoring chapter below

Single sign-on

• If you log in as admin using single sign-on, you will not have admin rights within Grafana. 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 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, routing web traffic that enters the cluster to the various applications;
• cert-manager acquires and stores Let's Encrypt certificates, enabling encrypted web traffic to all applications running in the cluster;
• Flux checks for application updates approved by the OpenAppStack team and installs them automatically.