diff --git a/docs/admin/client/auth.md b/docs/admin/client/auth.md
index ce9f0bb38..41205980a 100644
--- a/docs/admin/client/auth.md
+++ b/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.
diff --git a/docs/admin/overview.md b/docs/admin/overview.md
new file mode 100644
index 000000000..cfaf7aa0c
--- /dev/null
+++ b/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.
diff --git a/docs/admin/trial.md b/docs/admin/trial.md
index aee3eefc9..84ce1f8cd 100644
--- a/docs/admin/trial.md
+++ b/docs/admin/trial.md
@@ -1,24 +1,20 @@
# 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
@@ -26,18 +22,18 @@ 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.
diff --git a/docs/assets/into-cps-logo.png b/docs/assets/into-cps-logo.png
index dfc81fe0f..ca04a29f4 100644
Binary files a/docs/assets/into-cps-logo.png and b/docs/assets/into-cps-logo.png differ
diff --git a/docs/assets/into-cps-logo.svg b/docs/assets/into-cps-logo.svg
new file mode 100755
index 000000000..c37b7785f
--- /dev/null
+++ b/docs/assets/into-cps-logo.svg
@@ -0,0 +1,214 @@
+
+
+
+
\ No newline at end of file
diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio
new file mode 100755
index 000000000..a7c745341
--- /dev/null
+++ b/docs/user/examples/examples.drawio
@@ -0,0 +1,52 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md
index b2b6afad2..64b603316 100644
--- a/docs/user/examples/index.md
+++ b/docs/user/examples/index.md
@@ -1,4 +1,32 @@
-# DTaaS examples
+# DTaaS Examples
-The examples are hosted in
-[DTaaS examples repository](https://github.com/INTO-CPS-Association/DTaaS-examples)
+There are some example digital twins created for the DTaaS software.
+These examples are hosted in a dedicated
+[DTaaS examples github repository](https://github.com/INTO-CPS-Association/DTaaS-examples).
+
+Use the examples and follow the steps given in the **Examples** section to experience
+features of the DTaaS software platform and understand best practices for managing
+digital twins within the platform.
+
+## Copy Examples
+
+The first step is to copy all the example code into your
+user workspace within the DTaaS.
+Use these shell commands to copy all the examples
+into `/workspace/examples` directory.
+
+```bash
+#!/bin/bash
+cd /root/Desktop/
+wget -P workspace https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip
+unzip workspace/main.zip -d workspace
+mv workspace/DTaaS-examples-main workspace/examples
+rm workspace/main.zip
+```
+
+## Example List
+
+The digital twins provided in examples vary in their complexity. It is best
+to use the examples in the following order.
+
+1. [Mass Spring Damper](./mass-spring-damper/README.md)
diff --git a/docs/user/examples/mass-spring-damper/README.md b/docs/user/examples/mass-spring-damper/README.md
new file mode 100644
index 000000000..b5b2fb4d6
--- /dev/null
+++ b/docs/user/examples/mass-spring-damper/README.md
@@ -0,0 +1,81 @@
+# Mass Spring Damper
+
+## Overview
+
+The mass spring damper study comprises two mass spring dampers
+and demonstrates how the sucessive substitution technique can
+be used to ensure that a co-simulation is stable. More information
+about successive substitution and other co-simulation stabilization
+techniques, please see [this paper](https://arxiv.org/pdf/1702.00686v1).
+
+## Example Diagram
+
+
+
+## Example Structure
+
+There are two simulators included in the study, each representing a
+mass spring damper system. The first simulator calculates the mass
+displacement and speed of $m_1$ for a given force $F_k$ acting on mass $m_1$.
+The second simulator calculates force $F_k$ given a displacement and speed of
+mass $m_1$. By coupling these simulators, the evolution of the position of
+the two masses is computed.
+
+
+
+## Configuration of assets
+
+This example uses two models and one tool. The specific assets used are:
+
+| Asset Type | Names of Assets | Visibility | Reuse in Other Examples |
+|:---|:---|:---|:---|
+| Models | MassSpringDamper1.fmu | Private | Yes |
+| | MassSpringDamper2.fmu | Private | Yes |
+| Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes |
+
+This is a co-simulation based digital twin. The `co-sim.json` and `time.json`
+are two configuration files used for executing the digital twin.
+
+## Lifecycle Phases
+
+| Lifecycle Phase | Completed Tasks |
+| -------- | ------- |
+| Create | Installs Java Development Kit for Maestro tool |
+| Execute | Produces and stores output in data/mass-spring-damper/output directory|
+| Clean | Clears run logs and outputs |
+
+## Run the example
+
+To run the example, change your present directory.
+
+```bash
+cd workspace/examples/digital_twins/mass-spring-damper
+```
+
+If required, change the permission of files you need to execute, for example:
+
+```bash
+chmod +x lifecycle/create
+```
+
+Now, run the following scripts:
+
+### Create
+
+```bash
+lifecycle/create
+```
+
+### Execute
+
+```bash
+lifecycle/execute
+```
+
+## Examine the results
+
+The results can be found in the
+_workspace/examples/data/mass-spring-damper/output directory_.
+
+You can also view run logs in the
+_workspace/examples/digital_twins/mass-spring-damper_.
diff --git a/docs/user/examples/mass-spring-damper/dt-structure.png b/docs/user/examples/mass-spring-damper/dt-structure.png
new file mode 100755
index 000000000..2bee4055f
Binary files /dev/null and b/docs/user/examples/mass-spring-damper/dt-structure.png differ
diff --git a/docs/user/examples/mass-spring-damper/mass-spring-damper_multibody_system.png b/docs/user/examples/mass-spring-damper/mass-spring-damper_multibody_system.png
new file mode 100644
index 000000000..de2c5699b
Binary files /dev/null and b/docs/user/examples/mass-spring-damper/mass-spring-damper_multibody_system.png differ
diff --git a/mkdocs-github.yml b/mkdocs-github.yml
index 23e20f5d6..481dc9e75 100644
--- a/mkdocs-github.yml
+++ b/mkdocs-github.yml
@@ -17,6 +17,7 @@ theme:
nav:
- Home: index.md
- Admin:
+ - Overview: admin/overview.md
- Authentication: admin/client/auth.md
- Host Install:
- Trial: admin/trial.md
@@ -39,7 +40,10 @@ nav:
- Digital Twins:
- Create: user/digital-twins/create.md
- Lifecycle: user/digital-twins/lifecycle.md
- - Examples: https://github.com/INTO-CPS-Association/DTaaS-examples
+ - Examples:
+ - Overview: user/examples/index.md
+ - Mass Spring Damper: user/examples/mass-spring-damper/README.md
+ - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples
- FAQ: FAQ.md
- Developer:
- Overview: developer/index.md
@@ -61,6 +65,8 @@ extra_css:
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML
+ - https://polyfill.io/v3/polyfill.min.js?features=es6
+ - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
markdown_extensions:
- attr_list
diff --git a/mkdocs.yml b/mkdocs.yml
index 072c4cd8f..16ca86aca 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,6 +17,7 @@ theme:
nav:
- Home: index.md
- Admin:
+ - Overview: admin/overview.md
- Authentication: admin/client/auth.md
- Host Install:
- Trial: admin/trial.md
@@ -39,7 +40,10 @@ nav:
- Digital Twins:
- Create: user/digital-twins/create.md
- Lifecycle: user/digital-twins/lifecycle.md
- - Examples: https://github.com/INTO-CPS-Association/DTaaS-examples
+ - Examples:
+ - Overview: user/examples/index.md
+ - Mass Spring Damper: user/examples/mass-spring-damper/README.md
+ - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples
- FAQ: FAQ.md
- Developer:
- Overview: developer/index.md
@@ -61,7 +65,9 @@ extra_css:
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML
-
+ - https://polyfill.io/v3/polyfill.min.js?features=es6
+ - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
markdown_extensions:
- attr_list
- pymdownx.emoji:
diff --git a/servers/config/gateway/README.md b/servers/config/gateway/README.md
index 432155277..cc0b141d9 100644
--- a/servers/config/gateway/README.md
+++ b/servers/config/gateway/README.md
@@ -21,9 +21,10 @@ The default configuration uses two services at the following URLs:
```bash
docker run -d \
- --name "traefik-gateway" \
---network=host -v $PWD/traefik.yml:/etc/traefik/traefik.yml \
--v $PWD/dynamic:/etc/traefik/dynamic \
+--name "traefik-gateway" \
+--network=host -v "$PWD/traefik.yml:/etc/traefik/traefik.yml" \
+-v "$PWD/auth:/etc/traefik/auth" \
+-v "$PWD/dynamic:/etc/traefik/dynamic" \
-v /var/run/docker.sock:/var/run/docker.sock \
traefik:v2.10
```