From 22ecc1fe92fd20078683c2d9e76270937fa5e823 Mon Sep 17 00:00:00 2001 From: Prasad Talasila Date: Fri, 22 Dec 2023 15:08:31 +0100 Subject: [PATCH] Updates documentation (#383) - Adds new three water tank example - Adds docs on localhost install - Updates docs on authentication demo --- CITATION.cff | 35 ++ docs/user/examples/examples.drawio | 317 +++++++++++++++++- docs/user/examples/index.md | 1 + docs/user/examples/three-tank/README.md | 153 +++++++++ .../user/examples/three-tank/dt-structure.png | Bin 0 -> 65728 bytes docs/user/examples/three-tank/three-tank.png | Bin 0 -> 11806 bytes mkdocs-github.yml | 1 + mkdocs.yml | 1 + script/docs.sh | 2 +- servers/auth/README.md | 194 +++++++---- servers/auth/compose.yml | 6 +- 11 files changed, 633 insertions(+), 77 deletions(-) create mode 100644 CITATION.cff create mode 100644 docs/user/examples/three-tank/README.md create mode 100644 docs/user/examples/three-tank/dt-structure.png create mode 100644 docs/user/examples/three-tank/three-tank.png diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..78cd9d8f5 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,35 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +authors: +- family-names: "Talasila" + given-names: "Prasad" + orcid: "https://orcid.org/0000-0002-8973-2640" +title: "Digital Twin as a Service" +version: 0.3.0 +date-released: 2023-11-08 +url: "https://github.com/into-cps-association/DTaaS" +preferred-citation: + type: article + authors: + - family-names: "Talasila" + given-names: "Prasad" + orcid: "https://orcid.org/0000-0002-8973-2640" + - family-names: "Gomes" + given-names: "Cláudio" + orcid: "https://orcid.org/0000-0000-0000-0000" + - family-names: "Mikkelsen" + given-names: "Peter Høgh" + orcid: "https://orcid.org/0000-0003-2321-758X" + - family-names: "Gil" + given-names: "Santiago" + orcid: "https://orcid.org/0000-0002-1789-531X" + - family-names: "Kamburjan" + given-names: "Eduard" + orcid: "https://orcid.org/0000-0002-0996-2543" + - family-names: "Larsen" + given-names: "Peter Gorm" + orcid: "https://orcid.org/0000-0002-4589-1500" + conference-paper: "The 2023 IEEE International Conference on Digital Twin" + month: 8 + title: "Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users" + year: 2023 \ No newline at end of file diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio index 91072df68..685b8c348 100755 --- a/docs/user/examples/examples.drawio +++ b/docs/user/examples/examples.drawio @@ -1,6 +1,6 @@ - + - + @@ -401,6 +401,319 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 744715590..95fe9d98e 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -26,5 +26,6 @@ to use the examples in the following order. 1. [Water Tank Fault Injection](./water_tank_FI/README.md) 1. [Water Tank Model Swap](./water_tank_swap/README.md) 1. [Desktop Robotti and RabbitMQ](./drobotti-rmqfmu/README.md) +1. [Three Water Tanks with DT Manager Framework](./three-tank/README.md) :material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples) diff --git a/docs/user/examples/three-tank/README.md b/docs/user/examples/three-tank/README.md new file mode 100644 index 000000000..b57feed5d --- /dev/null +++ b/docs/user/examples/three-tank/README.md @@ -0,0 +1,153 @@ +# Three-Tank System Digital Twin + +## Overview + +The three-tank system is a simple case study allows us to represent a system +that is composed of three individual components that are coupled in +a cascade as follows: The first tank is connected to the input of +the second tank, and the output of the second tank is connected to +the input of the third tank. + +![Three-tank graphical representation](./three-tank.png) + +This example contains only the simulated components for +demonstration purposes; therefore, there is no configuration for +the connection with the physical system. + +The three-tank system case study is managed using the ```DTManager```, +which is packed as a jar library in the tools, and run from a java main file. +The ```DTManager``` uses Maestro as a slave for co-simulation, +so it generates the output of the co-simulation. + +The main file can be changed according to the application scope, i.e., +the ```/workspace/examples/tools/three-tank/TankMain.java``` +can be manipulated to get a different result. + +The ```/workspace/examples/models/three-tank/``` folder contains +the ```Linear.fmu``` file, which is a non-realistic model for a tank +with input and output and the ```TankSystem.aasx``` file for +the schema representation with Asset Administration Shell. +The three instances use the same ```.fmu``` file and the same schema +due to being of the same object class. +The ```DTManager``` is in charge of reading the values from +the co-simulation output. + +## Example Structure + +![Three-tank system architecture with DT Manager](./dt-structure.png) + +## Digital Twin Configuration + +This example uses two models, two tools, one data, and one script. +The specific assets used are: + +| Asset Type | Names of Assets | Visibility | Reuse in Other Examples | +|:---|:---|:---|:---| +| Model | Linear.fmu | Private | No | +| | TankSystem.aasx | Private | No | +| Tool | DTManager-0.0.1-Maestro.jar (wraps Maestro) | Common | Yes | +| | maestro-2.3.0-jar-with-dependencies.jar (used by DTManager) | Common | Yes | +| | TankMain.java (main script) | Private | No | +| Data | outputs.csv | Private | No | + +This DT has multiple configuration files. The _coe.json_ and +_multimodel.json_ are used by Maestro tool. The _tank1.conf_, _tank2.conf_ +and _tank3.conf_ are the config files for three different instances of +one model (Linear.fmu). + +## Lifecycle Phases + +The lifecycles that are covered include: + +| Lifecycle Phase | Completed Tasks | +| --------- | ------- | +| Create | Installs Java Development Kit for Maestro tool | +| Execute | The DT Manager executes the three-tank digital twin and produces output in ```data/three-tank/output``` directory | +| Terminate | Terminating the background processes and cleaning up the output | + +## Run the example + +To run the example, change your present directory. + +```bash +cd /workspace/examples/digital twins/three-tank +``` + +If required, change the execute permission of lifecycle scripts +you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +Installs Open Java Development Kit 11 and pip dependencies. +Also creates ```DTManager``` tool (DTManager-0.0.1-Maestro.jar) from source code. + +```bash +lifecycle/create +``` + +### Execute + +Execute the three-tank digital twin using DTManager. DTManager in-turn runs +the co-simulation using Maestro. Generates the co-simulation output.csv file +at `/workspace/examples/data/three-tank/output`. + +```bash +lifecycle/execute +``` + +### Terminate + +Stops the Maestro running in the background. Also stops any other +jvm process started during **execute** phase. + +```bash +lifecycle/terminate +``` + +### Clean + +Removes the output generated during execute phase. + +```bash +lifecycle/terminate +``` + +## Examining the results + +Executing this Digital Twin will generate a co-simulation output, +but the results can also be monitored from updating +the```/workspace/examples/tools/three-tank/TankMain.java``` with +a specific set of ```getAttributeValue``` commands, such as shown in +the code. + +That main file enables the online execution of the Digital Twin and +its internal components. + +The output of the co-simulation is generated to +the ```/workspace/examples/data/three-tank/output``` folder. + +In the default example, the co-simulation is run for 10 seconds in +steps of 0.5 seconds. +This can be modified for a longer period and different step size. +The output stored in ```outputs.csv``` contains the level, in/out flow, +and leak values. + +No data from the physical twin are generated/used. + +## References + +More information about the DT Manager is available at: + +```txt +D. Lehner, S. Gil, P. H. Mikkelsen, P. G. Larsen and M. Wimmer, +"An Architectural Extension for Digital Twin Platforms to Leverage +Behavioral Models," 2023 IEEE 19th International Conference on +Automation Science and Engineering (CASE), Auckland, New Zealand, +2023, pp. 1-8, doi: 10.1109/CASE56687.2023.10260417. +``` diff --git a/docs/user/examples/three-tank/dt-structure.png b/docs/user/examples/three-tank/dt-structure.png new file mode 100644 index 0000000000000000000000000000000000000000..b0604c1bbc3cbd02a65a233309c4c51ae928f41d GIT binary patch literal 65728 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 literal 0 HcmV?d00001 diff --git a/mkdocs-github.yml b/mkdocs-github.yml index 3deee0e89..28e962a61 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -54,6 +54,7 @@ nav: - Water Tank Fault Injection: user/examples/water_tank_FI/README.md - Water Tank Model Swap: user/examples/water_tank_swap/README.md - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md + - Three Water Tanks: user/examples/three-tank/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/mkdocs.yml b/mkdocs.yml index b7a8809d5..b6b5035aa 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ nav: - Water Tank Fault Injection: user/examples/water_tank_FI/README.md - Water Tank Model Swap: user/examples/water_tank_swap/README.md - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md + - Three Water Tanks: user/examples/three-tank/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/script/docs.sh b/script/docs.sh index 4978519a6..6058537a3 100755 --- a/script/docs.sh +++ b/script/docs.sh @@ -50,4 +50,4 @@ mv site/index.html . rm -rf site git add . -git commit -m "docs for ${COMMIT_HASH} commit" \ No newline at end of file +git commit --no-verify -m "docs for ${COMMIT_HASH} commit" \ No newline at end of file diff --git a/servers/auth/README.md b/servers/auth/README.md index 3019f2ac4..a96304a5b 100644 --- a/servers/auth/README.md +++ b/servers/auth/README.md @@ -12,6 +12,88 @@ Within docker, images of the following container are used: This is an example version of any microservice that should lie behind the OAuth. +## Ready Reckoner + +You need an +[instance-wide authentication type](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application) +on Gitlab. If you use as your authentication provider, +you can only authenticate a single user. For the table below, +has been used as example URL of OAuth provider + +| Gitlab Variable Name | Variable name in compose.yml | Default Value | +| :------------------- | :------------------------------------ | :----------------------------------------| +| OAuth Provider | PROVIDERS_GENERIC_OAUTH_AUTH_URL | | +| | PROVIDERS_GENERIC_OAUTH_TOKEN_URL | | +| | PROVIDERS_GENERIC_OAUTH_USER_URL | | +| Application ID | PROVIDERS_GENERIC_OAUTH_CLIENT_ID | | +| Secret | PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET | | +| Callback URL | | | +| Scopes | | read_user | +| Logout URL for demo | | | +|| + +## Configure Authentication Rules + +The Traefik forward auth microservices requires configuration rules to manage +authentication for different URL paths. +The `conf` file can be used to configure the specific rules. +There are broadly three kinds of URLs: + +### Public Path Without Authentication + +To setup a public page, an example is shown below. + +```text +rule.noauth.action=allow +rule.noauth.rule=Path(`/public`) +``` + +Here, 'noauth' is the rule name, and should be changed to suit rule use. +Rule names should be unique for each rule. +The 'action' property is set to "allow" to make the resource public. +The 'rule' property defines the path/route to reach the resource. + +### Common to All Users + +To setup a common page that requires Gitlab OAuth, +but is available to all users of the Gitlab instance: + +```text +rule.all.action=auth +rule.all.rule=Path(`/os`) +``` + +The 'action' property is set to "auth", to enable Gitlab +OAuth before the resource can be accessed. + +### Selective Access + +Selective Access refers to the scenario of allowing access to a URL path +for a few users. To setup selective access to a page: + +```text +rule.onlyu1.action=auth +rule.onlyu1.rule=Path(`/user1`) +rule.onlyu1.whitelist = user1@localhost +``` + +The 'whitelist' property of a rule defines a comma separated list +of email IDs that are allowed to access the resource. +While signing in users can sign in with either their username or email ID +as usual, but the email ID corresponding to the +account should be included in the whitelist. + +This restricts access of the resource, +allowing only users mentioned in the whitelist. + +### Limitation + +The rules in _conf_ file are not dynamically loaded into +the **traefik-forward-auth** microservice. Any change in the _conf_ file requires +retart of **traefik-forward-auth** for the changes to take effect. +All the existing user sessions get invalidated when +the **traefik-forward-auth** restarts. + ## Run the example You should have docker setup to be able to run this. @@ -22,36 +104,50 @@ Docker Desktop for Linux is preferred. - This service works based on 2 files, servers/auth/compose.yml and servers/auth/conf. - In the compose.yml, under the traefik-forward-auth service volumes, - please replace the correct file path for - servers/auth/conf file (on the left hand side of ':'). -- Also fill in the CLIENT_ID, CLIENT_SECRET fields. + please replace the correct absolute file path for + servers/auth/conf file in the volume mapping of + **traefik-forward-auth** container.. +- Also fill in the OAUTH details in compose.yml as per the table given above. - No other changes should be made to compose.yml. -- Run: +- Finally, run: -```bash -docker compose up -d --remove-orphans -``` + ```bash + docker compose up -d --remove-orphans + ``` -The microservice is now running. +The microservices start up and provide access to +the following URL paths. + +| URL Path | Access Granted to | +|:------------|:---------------| +| | everyone including unauthenticated users | +| | user1 and user2 | +| | user1 | +| | user2 | +|| ## View the example -- Try heading over to . - This is a public, accessible to all, copy of the webserver. - It still passes through the AuthServer (traefik-forward-auth), - however this Path is set to allow access to all, - instead of any authentication. - You should be able to see this page with any email ID/ even without signing in. +### Public + +Try heading over to . +This is a public, accessible to all, copy of the webserver. +It still passes through the AuthServer (traefik-forward-auth), +however this Path is set to allow access to all, +instead of any authentication. +You should be able to see this page without even signing in. + +### Authenticated users - Head over to . This page requires Gitlab OAuth and is not public. - You will be redirected to Gitlab. Sign in if you aren't already signed in. - user1 (user1@localhost) /user2 (user2@localhost) + _user1 (user1@localhost) / user2 (user2@localhost)_ accounts can be used to sign into the Gitlab instance. - On Gitlab you will be asked to authorize sharing some - account data with a "AuthTry" application. - Click on the "Authorize" button. + account data for the application. + Click on the **Authorize** button. - You will be redirect to the whoami server page showing information about your system. Any account that passes the Gitlab OAuth or @@ -92,51 +188,8 @@ The microservice is now running. - You will automatically be able to see this page, without any Auth process/ new access tokens. - This page is still visible even though you have logged out of Gitlab. - This is because you haven't logged out of the OAuth. - -## Configuration - -The conf file can be used to configure the specific rules. - -- To setup a public page, an example is shown below. - - ```text - rule.noauth.action=allow - rule.noauth.rule=Path(`/public`) - ``` - - Here, 'noauth' is the rule name, and should be changed to suit rule use. - Rule names should be unique for each rule. - The 'action' property is set to "allow" to make the resource public. - The 'rule' property defines the path/route to reach the resource. - -- To setup a common page that requires Gitlab OAuth, - but is available to all users of the Gitlab instance: - - ```text - rule.all.action=auth - rule.all.rule=Path(`/os`) - ``` - - The 'action' property is set to "auth", to enable Gitlab - OAuth before the resource can be accessed. - -- To setup selective access to a page: - - ```text - rule.onlyu1.action=auth - rule.onlyu1.rule=Path(`/user1`) - rule.onlyu1.whitelist = user1@localhost - ``` - - The 'whitelist' property of a rule defines a comma separated list - of email IDs that are allowed to access the resource. - While signing in users can sign in with either their username or email ID - as usual, but the email ID corresponding to the - account should be included in the whitelist. - - This restricts access of the resource, - allowing only users mentioned in the whitelist. + This is because you haven't logged out of the OAuth session + managed by traefik forward auth. ## Adding/Removing a service @@ -226,15 +279,14 @@ access to the dummy service. behind this Authentication, only accesible through the Traefik reverse proxy. - Dynamic rule addition is also an open issue. -- Please refer to - . - This microservice is based on this repository. +- The Traefik Forward Auth code is available + [online](https://github.com/thomseddon/traefik-forward-auth). ## Disclaimer -The server currently has a 8 second timeout on requests. -This might cause some requests to timeout, -usually due to internet connectivity -and recieve a 503 - Service Unavailable. -Please try again in case this happens. -This is an open issue. +There is an 8 second timeout on OAuth requests sent to Gitlab. +If the OAuth signin process is not complete before eight seconds, +Gitlab cancels the signin request and gives +_503 - Service Unavailable_ message. +The timelimit variable has not been found in gitlab.rb config file; +timelimit is probably built into Gitlab code. diff --git a/servers/auth/compose.yml b/servers/auth/compose.yml index 20de649d2..dd120e2d3 100644 --- a/servers/auth/compose.yml +++ b/servers/auth/compose.yml @@ -53,9 +53,9 @@ services: - /home/astitva/Desktop/DTaaS/servers/auth/conf:/rules environment: - DEFAULT_PROVIDER=generic-oauth - - PROVIDERS_GENERIC_OAUTH_AUTH_URL=https://maestro.cps.digit.au.dk/oauth/authorize - - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=https://maestro.cps.digit.au.dk/oauth/token - - PROVIDERS_GENERIC_OAUTH_USER_URL=https://maestro.cps.digit.au.dk/api/v4/user + - PROVIDERS_GENERIC_OAUTH_AUTH_URL=https://gitlab.foo.com/oauth/authorize + - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=https://gitlab.foo.com/oauth/token + - PROVIDERS_GENERIC_OAUTH_USER_URL=https://gitlab.foo.com/api/v4/user - PROVIDERS_GENERIC_OAUTH_CLIENT_ID=xxxx - PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET=xxxx - PROVIDERS_GENERIC_OAUTH_SCOPE=read_user