Commit a9e3973e authored by Maarten de Waard's avatar Maarten de Waard

Merge branch '486_add_rocketchat_sso_instructions' into 'master'

Improve installation and usage docs

Closes #505

See merge request openappstack/openappstack!222
parents cd570d97 19f2905b
......@@ -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
......@@ -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.
......@@ -50,6 +50,10 @@ Filter out redundant `flux` messages:
{ app = "flux" } !~ "(unchanged | event=refreshed | method=Sync | component=checkpoint)"
Debug oauth2 single sign-on with rocketchat:
{container_name=~"(hydra|rocketchat)"}
#### Cert-manager
......
......@@ -21,26 +21,20 @@ 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.
## User panel
## Usage
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 go through the [Usage documentation](./usage.md) and make sure you
complete all steps.
## Nextcloud
### Logging into Nextcloud
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.
Please browse to https://files.oas.example.org and try to log in using single
sign-on. Use the button labeled `Login with OpenAppStack`.
Please try logging in with your admin account and configure the email settings
as shown in the Usage doc.
After that please login with the user you created in the user panel.
### Nextcloud client application
......@@ -48,7 +42,7 @@ panel.
* 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
......@@ -59,17 +53,30 @@ From the main Nextcloud webpage, please try to create a new office document, by
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.
* 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.
* 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.
## Rocketchat
You can find Rocketchat at https://chat.oas.example.org.
Once you configured Rocketchat for single sign-on as desribed in the Usage docs
please login using single sign-on as `admin` and afterwards as the user you
created.
## Wordpress
## Rocket.Chat
You can find Wordpress at https://www.oas.example.org.
Please try to login as the new user you created earlier by pressing "Log in" and
using the `Login with OpenID Connect` button.
You can find Rocket.Chat at https://chat.oas.example.org. Please go there and
try to log in.
At the moment Administrator privileges will not be available for single sign-on
users of WordPress. You can sign in with the automatically created administrator
account. The username is `admin` and the password can be found in the
`wordpress_admin_password` file in the `secrets` folder of your provisioning
machine's config directory.
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
......
# 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 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.
#### Single sign-on
Until we [fully automate SSO integration for Rocketchat](https://open.greenhost.net/openappstack/openappstack/issues/516)
manual intervention is neccessary to activate it. 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` (change `oas.example.org` to your domain)
- 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 log in to Rocketchat you will be able to use single sign-on using
the `Login` button.
### 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:
* [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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment