Updates to admin and example documentation (#190)

  - Updates the overview and authentication pages of admin section
  - Adds documentation for Mass Spring Damper example

---------
Co-authored-by: nichlaes
Co-authored-by: Asti <[email protected]>
Co-authored-by: Astitva Sehgal <[email protected]>

docs/admin/client/auth.md

@@ -1,57 +1,55 @@
-# OAuth Authentication for React Client Website
-
-The react client website uses OAuth authentication protocol for user
-authentication. The PKCE authentication flow of OAuth protocol is used
-for the client website. The authentication has to be setup on a gitlab
-server.
-**An oauth application needs to be created on a gitlab instance under admin user**.
-Then all other users can use the same gitlab instance for oauth authentication.
-This means commercial gitlab.com can not be used for multi-user authentication
-system required by DTaaS. You will need to run an on-premise instance of gitlab.
-You can use
-[gitlab omnibus docker](https://docs.gitlab.com/ee/install/docker.html) for
-this purpose. Please setup OAuth application as
-[instance wide authentication type](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application).
-
-Before setting up oauth application on gitlab, you need to first decide on the
-hostname for your website. We recommend using a self-hosted gitlab instance which
-will be used in the other parts of the DTaaS application.
-
-Two more URLs are required for the PKCE authentication flow to work properly.
-They are the **callback URL** and **logout URL**. The callback URL tells the oauth
-provider the URL of the page that all the signed in users are shown. This URL will
-be different from the landing homepage of the DTaaS application. The logout URL is
-the URL that will be shown after a user logs out.
-
-Here is an example for hosting a DTaaS application without any basename.
+# Setting Up OAuth
 
-```txt
-DTaaS application URL: https://foo.com
-Gitlab instance URL: https://foo.gitlab.com
-Callback URL: https://foo.com/Library
-Logout URL: https://foo.com
-```
+To enable user authentication on DTaaS React client website, you will use
+the OAuth authentication protocol, specifically the PKCE authentication flow.
+Here are the steps to get started:
+
+**1. Choose Your GitLab Server:**
+
+- You need to set up OAuth authentication on a GitLab server.
+  The commercial gitlab.com is not suitable for multi-user authentication
+  (DTaaS requires this), so you'll need an on-premise GitLab instance.
+- You can use
+  [GitLab Omnibus Docker for this purpose](https://docs.gitlab.com/ee/install/docker.html).
+- Configure the OAuth application as
+  an [instance-wide authentication type](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application).
+
+**2. Determine Your Website's Hostname:**
+
+- Before setting up OAuth on GitLab, decide on the hostname for your website.
+  It's recommended to use a self-hosted GitLab instance, which you will use in
+  other parts of the DTaaS application.
+
+**3. Define Callback and Logout URLs:**
+
+- For the PKCE authentication flow to function correctly, you need two URLs:
+  a callback URL and a logout URL.
+- The callback URL informs the OAuth provider of the page where
+  signed-in users should be redirected. It's different from the landing
+  homepage of the DTaaS application.
+- The logout URL is where users will be directed after logging out.
+
+**4. OAuth Application Creation:**
+
+- During the creation of the OAuth application on GitLab, you need to specify
+  the scope. Choose openid, profile, read_user, read_repository, and api scopes.
 
-During the creation of oauth application on gitlab, you need to decide on the
-scope of this oauth application.
-Choose `openid profile read_user read_repository api` scopes.
+**5. Application ID:**
 
-After successful creation of oauth application, gitlab generates an application
-ID. This application ID is a long string of HEX values. You need to note this
-down and use in configuration files. An example oauth Client ID is:
-`934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0`.
+- After successfully creating the OAuth application, GitLab generates
+  an application ID. This is a long string of HEX values that you will need for
+  your configuration files.
 
-You need the following information from the OAuth application registered on Gitlab:
+**6. Required Information from OAuth Application:**
 
-| Gitlab Variable Name | Variable name in Client env.js | Default Value |
-|:---|:---|:---|
-| OAuth Provider | REACT_APP_AUTH_AUTHORITY | https://gitlab.foo.com/ |
-| Application ID | REACT_APP_CLIENT_ID |
-| Callback URL | REACT_APP_REDIRECT_URI | https://foo.com/Library |
-| Scopes | REACT_APP_GITLAB_SCOPES | openid, profile, read_user, read_repository, api |
+- You will need the following information from the OAuth application registered on GitLab:
 
-The same **URLs** and **Client ID** are useful for both the regular hosting of
-DTaaS application and also as the CI/CD server to be used for the development work.
+|GitLab Variable Name|Variable Name in Client env.js|Default Value|
+|---|---|---|
+|OAuth Provider|REACT_APP_AUTH_AUTHORITY|[https://gitlab.foo.com/](https://gitlab.foo.com/)|
+|Application ID|REACT_APP_CLIENT_ID||
+|Callback URL|REACT_APP_REDIRECT_URI|[https://foo.com/Library](https://foo.com/Library)|
+|Scopes|REACT_APP_GITLAB_SCOPES|openid, profile, read_user, read_repository, api|
 
 ## Development Environment
 
@@ -92,7 +90,7 @@ All of these instances can use the same gitlab instance for authentication.
 ||
 
 If you are hosting multiple DTaaS instances on the same server,
-do not a DTaaS with a null basename on the same server.
+do not install DTaaS with a null basename on the same server.
 Even though it works well, the setup is confusing to setup
 and may lead to maintenance issues.
 

docs/admin/overview.md

@@ -0,0 +1,28 @@
+# Overview
+
+## What is the goal
+
+The goal is to set up the DTaaS infrastructure in order to enable
+your users to use the DTaaS.
+As an admin you will administrate the users and the servers of the system.
+
+## What are the requirements
+
+### OAuth Provider
+
+You need to have an OAuth Provider running, which the DTaaS can use for
+authentication. This is described further in
+the [authentication section](./client/auth.md).
+
+## What to install
+
+The DTaaS can be installed in different ways. Each version is for different purposes:
+
+- [Trial installation on single host](./trial.md)
+- [Production installation on single host](./host.md)
+- On [one](vagrant/single-machine.md) or [two](vagrant/two-machines.md)
+  Vagrant virtual machines
+- Seperater Packages: [client website](client/CLIENT.md) and
+  [lib microservice](servers/lib/LIB-MS.md)
+
+Following the installation that fit your usecase.

docs/admin/trial.md

@@ -1,43 +1,39 @@
 # Trial Installation
 
-The software can be installed either on
-Ubuntu Server 22.04 Operating System or
-on vagrant virtual machine(s).
-
-A single step install script is helpful in performing a
-trial run of the software. This script installs DTaaS software
-with default credentials and users on a Ubuntu server 22.04
-Operating System.
+To try out the software, you can install it on either an Ubuntu Server 22.04
+Operating System or within a Vagrant virtual machine.
+Provided is a one-step installation script. This script sets up
+the DTaaS software with default credentials and users.
 You can use it to check a test installation of DTaaS software.
 
 ## Pre-requisites
 
-### Domain name
+### 1. Domain name
 
 You need a domain name to run the application. The install script
-assumes **foo.com** to be your domain name. Please change it
-to a relevant one.
+assumes **foo.com** to be your domain name. You will change this
+after running the script.
 
-### Gitlab OAuth application
+### 2. Gitlab OAuth application
 
 The DTaaS react website requires Gitlab OAuth provider.
 If you need more help with this step, please see
 the [Authentication page](client/auth.md).
 
 You need the following information from the OAuth application registered on Gitlab:
 
-| Gitlab Variable Name | Variable name in Client env.js | Default Value |
-|:---|:---|:---|
-| OAuth Provider | REACT_APP_AUTH_AUTHORITY | https://gitlab.foo.com/ |
-| Application ID | REACT_APP_CLIENT_ID |
-| Callback URL | REACT_APP_REDIRECT_URI | https://foo.com/Library |
-| Scopes | REACT_APP_GITLAB_SCOPES | openid, profile, read_user, read_repository, api |
+| Gitlab Variable Name | Variable name in Client env.js | Default Value                                    |
+| :------------------- | :----------------------------- | :----------------------------------------------- |
+| OAuth Provider       | REACT_APP_AUTH_AUTHORITY       | https://gitlab.foo.com/                          |
+| Application ID       | REACT_APP_CLIENT_ID            |
+| Callback URL         | REACT_APP_REDIRECT_URI         | https://foo.com/Library                          |
+| Scopes               | REACT_APP_GITLAB_SCOPES        | openid, profile, read_user, read_repository, api |
 
 You can also see
 [Gitlab help page](https://docs.gitlab.com/ee/integration/oauth_provider.html)
 for getting the Gitlab OAuth application details.
 
-### Install
+## Install
 
 ```bash
 wget https://raw.githubusercontent.com/INTO-CPS-Association/DTaaS/feature/distributed-demo/deploy/single-script-install.sh
@@ -46,3 +42,18 @@ bash single-script-install.sh
 
 !!! warning
     This test installation has default credentials and is thus highly insecure.
+
+## Post install
+
+After the install-script. Please change **foo.com** and Gitlab OAuth details
+to your local settings in the following files.
+
+```txt
+~/DTaaS/client/build/env.js
+~/DTaaS/servers/config/gateway/dynamic/fileConfig.yml
+```
+
+## Sanity check
+
+Now when you visit your domain, you should be able to login through your
+OAuth Provider and be able to access the DTaas web UI.