add documentation for administrators/managers

docs/usage.rst → docs/applications.rst

-Usage
-=====
-
-Stackspin User panel
---------------------
-
-After all the applications are installed, the first thing to do is log in to
-`https://admin.stackspin.example.org <https://admin.stackspin.example.org>`__.
-This is the "user panel" , a place where you can create, edit and delete users.
-These users can be used to log in to the applications listed below.
-You can log in with the user "admin". The password can be found by running
-
-.. code:: bash
-
-   python3 -m stackspin stackspin.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.stackspin.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:`install_additional_apps` of the installation procedure.
-
-For creating users follow the `user creation documentation
-<https://docs.stackspin.net/projects/user-panel/en/latest/#creating-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.
-
-Links to all available apps are shown in the userpanel dashboard, which can
-be used to access these apps without a need to bookmark all URLs.
+Applications
+============
 
 Core applications
 -----------------
@@ -45,6 +7,17 @@ Core applications
 These applications are available after the installation is completed
 successfully:
 
+Dashboard
+~~~~~~~~~
+
+The Dashboard is an application developed specifically for Stackspin. It allows
+you to manage Stackspin's central user database. Soon, the dashboard
+will also allow you to configure, install and remove applications and set access
+rights for users.
+
+Administrators can read how to use the Dashboard in
+:ref:`manage_stackspin:Manage Stackspin`
+
 Grafana
 ~~~~~~~
 

docs/index.rst

@@ -29,17 +29,18 @@ For more information, go to `the Stackspin website`_.
    installation/install_cli
    installation/create_cluster
    installation/install_stackspin
+   installation/testing
 
 .. toctree::
    :maxdepth: 2
    :caption: Usage
 
-   usage
-   testing
+   manage_stackspin
+   applications
 
 .. toctree::
    :maxdepth: 2
-   :caption: Administration
+   :caption: System Administration
 
    logging
    maintenance

docs/testing.rst → docs/installation/testing.rst

 .. _testing_guide:
 
-Testing guide
-=============
+Test your installation
+======================
 
-Great that you want to take Stackspin for a test drive !
+Great that you want to take Stackspin for a test drive!
 This guide contains instructions to get you going, some pointers on what we think
 would be useful to test, and guesses at what results of those tests
 would be useful to write down. At any point please feel invited to test
@@ -20,7 +20,7 @@ Stackspin installation
 ----------------------
 
 First we’d like you to setup an Stackspin cluster by yourself,
-following the :ref:`installation_overview` and :ref:`usage:Usage` documentation and make sure
+following the :ref:`installation_overview` documentation and make sure
 you complete all steps.
 
 Command line tests
@@ -34,11 +34,12 @@ feedback.
 Testing Instructions for all apps
 ---------------------------------
 
-Please login using single sign-on as ``admin`` and see if you have admin
-rights granted (usually there’s an app specific admin panel available or
-admin functionality like configuring users). Afterwards logout and login
-again as the non-admin single-sign-on user you created earlier in the
-Stackspin admin panel. You should *not* have any admin privileges now.
+Please log in on https://dashboard.stackspin.example.org using single sign-on
+with your admin user email address and see if you have admin rights granted
+(usually there’s an app specific admin panel available or admin functionality
+like configuring users).  Afterwards logout and log in again as the non-admin
+single-sign-on user you created earlier in the Stackspin admin panel. You should
+*not* have any admin privileges now.
 
 Testing Instructions for specific apps
 --------------------------------------
@@ -50,7 +51,7 @@ Please browse to Nextcloud using the link from your user dashboard app
 list and try to log in using single sign-on. Use the button labeled
 ``Login with Stackspin``. 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.
+After that please log in with the user you created in the user panel.
 
 Files & synchronization
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -72,7 +73,7 @@ Nextcloud sync applications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - Please try syncing with your smartphone or desktop using one of the apps
-  mentioned in :ref:`Usage:Nextcloud`.
+  mentioned in :ref:`applications:nextcloud`.
 
 Onlyoffice
 ~~~~~~~~~~
@@ -115,7 +116,7 @@ Providing feedback
 ------------------
 
 If you have not done so already, please create an account on
-https://open.greenhost.net (or login with your existing github account)
+https://open.greenhost.net (or log in with your existing github account)
 and `create a new
 issue <https://open.greenhost.net/stackspin/stackspin/issues/new>`__
 using the ``Feedback`` template.

docs/manage_stackspin.rst

+Manage Stackspin
+================
+
+After all the applications are installed, the first thing to do is log in to
+https://dashboard.stackspin.example.org. The Dashboard is the starting point for
+Stackspin administrators. Here you can create, edit and delete new users, as
+well as see all the applications that run on your Stackspin cluster.
+
+Your first login can happen in one of two ways:
+
+1. Use the email address that was used during setup.
+
+   The admin email address has an account already. If you have access to its
+   mailbox, press "Sign in" in the browser and then press "Forget password?" to
+   start a password recovery procedure.
+
+2. If you do not have access to the administrator email address, ask your system
+   administrator to run the following command on their "provisioning machine"
+   and share the admin credentials with you:
+
+   .. code:: bash
+
+      python3 -m stackspin stackspin.example.org admin-credentials
+
+   Note: these are the setup credentials, they will not be updated when you
+   change the admin user's password.
+
+Dashboard
+---------
+
+After logging in, you will see an overview of all the installed applications.
+The "Launch app" button on this screen will bring you to the application's
+screen. If see a login screen, use the "log in with Stackspin" button to log in
+with your current user. You will not have to enter credentials, because you are
+already logged in via the Dashboard.
+
+Users
+-----
+
+The Dashboard also features a "Users" tab, where you can manage the Stackspin
+users. At the moment, all users will be able to log into all applications on
+your cluster with the "Log in with Stackspin" button. More fine grained control
+will be added in the future.
+
+To create a new user, click the "Add new user" button. You need to specify the
+user's (full) name under "Name" and a valid email address under "Email".
+
+Once you have created the user, they can use the "Forget password?" button on
+any application's "log in with Stackspin" screen to set up their password for
+the first time.
+
+.. note::
+
+   The Dashboard currently allows all users to manage the other users. In the
+   (near) future, only users with "admin" privileges will be allowed to add,
+   edit and remove other users.
+
+   Only add users for people that you trust.
+
+To edit a user's name or email address, or delete a user, press the "Configure"
+button on the right side in the user table.
+
+If you want to delete several users, you can select them in the Users overview,
+using the select buttons on the left side. Then press the "Delete" button on the
+top right of the table.
+
+.. note::
+
+   **A note on deleting users**
+
+   Deleting users from the Dashboard makes sure they can't log into applications
+   anymore. However, the dashboard cannot control the user's data inside other
+   applications.
+
+   To completely remove users from all the applications, you will need to remove
+   them from inside the application's admin settings as well. Refer to the
+   documentation of the specific application to see how that should be done.
+
+   If you only remove a user from the dashboard, but not from the application,
+   it is possible that this user keeps access to the application through
+   sessions inside application clients (for example the Zulip or Nextcloud
+   desktop clients). These sessions can also typically be ended through the
+   application's admin interface.

docs/troubleshooting.rst

@@ -245,7 +245,7 @@ Look for these lines:
 Copy the whole ``export`` line into your terminal. In *the same terminal
 window*, ``kubectl`` will connect to your cluster.
 
-HTTPS Certificates
+HTTPS certificates
 ------------------
 
 Stackspin uses `cert-manager <https://docs.cert-manager.io/en/latest/>`__ to