Updates documentation (Improves #114)

.codeclimate.yml

@@ -20,7 +20,7 @@ plugins:
   fixme:
     enabled: true
   markdownlint:
-    enabled: true  
+    enabled: true
   shellcheck:
     enabled: true
 

.mdl_style.rb

@@ -0,0 +1,4 @@
+all
+rule 'MD013', :ignore_code_blocks => true
+rule 'MD013', :tables => false
+rule 'MD046', :indented => true

.mdlrc

@@ -1,5 +1 @@
-git_recurse true
-all
-rule 'MD013', :ignore_code_blocks => true
-rule 'MD013', :tables => false
-rule 'MD046', :indented
+style '.mdl_style.rb'

README.md

@@ -1,26 +1,29 @@
-# Motivation
+# :factory: :left_right_arrow: :busts_in_silhouette: Digital Twin as a Service
 
-The Digital Twin as a Service (DTaaS) software
-is useful to create and run digital twins.
-The digital twins that are running can be
-used as service by other users.
-These users need not be members of
-the DTaaS software platform itself.
+## :grinning: Motivation
 
-There is an overview of the software available for:
+The Digital Twin as a Service (DTaaS) software platform is useful
+to <font color="orange"> **Build, Use and Share** </font> digital twins (DTs).
 
-* General users -
-  [overview slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-short-intro.pdf)
-  and
-  [overview video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-short-intro.mp4),
-  [feature walkthrough](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/dtaas-v0.2.0-demo.mp4)
-* Developers - [slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-overview.pdf)
-  and [video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-overview.mkv).
+<font color="orange">**Build**</font>: The DTs are built on the software platform
+using the reusable DT components available on the platform.
 
-There is also a
-[research paper draft](https://arxiv.org/abs/2305.07244)
-if you are interested in
-reading the scientific roadmap for this software.
+<font color="orange">**Use**</font>: Use the DTs on the software platform.
+
+<font color="orange">**Share**</font>: Share ready to use DTs with other users.
+It is also possible to share the services offered by one DT with other users.
+
+## :rocket: Install and Use
+
+Please use the latest release available on
+the [releases page](https://github.com/INTO-CPS-Association/DTaaS/releases)
+and its [documentation](https://into-cps-association.github.io/DTaaS/)
+to install and use the DTaaS software platform.
+
+You are welcome to open an [issue](https://github.com/INTO-CPS-Association/DTaaS/issues/new/choose)
+if there is a suggestion to improve the software.
+
+## :hammer_and_wrench: Development Setup
 
 This is a mono repo containing code for
 both the web client and the microservices code base.
@@ -29,83 +32,11 @@ Only the [web client](client) and
 components are functional at present.
 Everything else is a work-in-progress.
 
-## Documentation
-
-The software comes with
-[documentation](https://into-cps-association.github.io/DTaaS/)
-for administrators and users.
-You are welcome to open an issue
-if there is a suggestion on improving the documentation.
-
-## Installation
-
-The software can be installed either on
-Ubuntu Server 22.04 Operating System or
-on vagrant virtual machine(s).
-The installation instructions and scripts in `deploy/`
-should help you get started.
-If you face any issues,
-please open an
-[issue](https://github.com/INTO-CPS-Association/DTaaS/issues/new/choose).
-
-Some of the services like InfluxDB
-require a dedicated hostname.
-Thus successful installation of these services
-is dependent on your ability to use
-multiple hostnames for different services.
-There are dedicated installation scripts
-for services in `script/`.
-
-## Development Setup
-
-The rest of the information on this page
-is aimed at current and potential contributors
-to DTaaS software development.
-
-To install the development environment, run
-
-```bash
-bash script/env.sh
-```
-
-There is a script to download all the docker containers used in the project.
-You can download them using
-
-```bash
-bash script/docker.sh
-```
-
-**CAVEAT**: The docker images are large and are likely to consume
-about 5GB of bandwidth and 15GB of space.
-You will have to download the docker images on a really good network.
-
-Before you make commits, please install the git hooks provided in the repository.
-
-```bash
-bash script/configure-git-hooks.sh
-```
-
-This will ensure that your commits are formatted
-correctly and that the unittests pass before you
-push your changes.
-Be aware that the tests take a long time to run.
-If you want to skip the tests or formatting,
-you can use the `--no-verify` flag
-on `git commit` or `git push`.
-
-### Infrastructure Components
-
-The application uses
-[Træfik](https://github.com/traefik/traefik) and
-[ML Workspace](https://github.com/ml-tooling/ml-workspace)
-open-source components.
-It is possible to run jupyterlab notebooks,
-[Grafana servers](script/grafana.sh),
-[InfluxDB](script/influx.sh) and
-[RabbitMQ](https://github.com/rabbitmq/rabbitmq-server)
-as part of the DTaaS software.
+Please see the
+[developer documentation](https://into-cps-association.github.io/DTaaS/development/developer/index.html)
+for more details.
 
-## License
+## :balance_scale: License
 
 This software is owned by
 [The INTO-CPS Association](https://into-cps.org/)

client/.madgerc

@@ -0,0 +1,18 @@
+{
+	"fontSize": "10px",
+  "tsconfig": "tsconfig.json",
+  "fileExtensions": ["ts", "tsx", "js", "jsx"],
+  "backgroundColor": "#FFFFFF",
+  "textColor": "#FFFFFF",
+  "nodeColor": "black",
+  "noDependencyColor": "green",
+  "cyclicNodeColor": "red",
+  "edgeColor": "green",
+	"graphVizOptions": {
+		"G": {
+			"rankdir": "TB",
+      "layout": "neato",
+      "splines": "curved"
+		}
+	}
+}

client/README.md

@@ -13,6 +13,7 @@ cd client
 yarn install    #install the nodejs dependencies
 yarn format     #format .ts[x] and .js[x] files with prettier.
 yarn syntax     #perform linting and static analysis
+yarn graph       # generate dependency graphs in the code
 yarn build      #build the react app into build/ directory
 yarn develop    #start the development server without building. Great for live edits.
 
@@ -24,18 +25,23 @@ yarn start      #start the application
 yarn clean      #clean the directory of temporary files
 ```
 
-It is also possible to run different types of tests using the yarn test command by passing different flags:
+It is also possible to run different types of tests using the yarn
+test command by passing different flags:
+
 ```bash
 yarn test -a   #run all tests
 yarn test -u   #run unit tests
 yarn test -i   #run integration tests
 yarn test -e   #run end-to-end tests
 ```
+
 ---
 
 ## Authentication
 
-The react client website uses OAuth authentication. The [authentication page](../docs/admin/client/auth.md) provides details on setting up oauth authentication for the client application.
+The react client website uses OAuth authentication.
+The [authentication page](../docs/admin/client/auth.md) provides details
+on setting up oauth authentication for the client application.
 
 ## Custom configuration
 

client/package.json

@@ -20,7 +20,8 @@
     "configapp": "script/config.bash",
     "start": "script/start.bash",
     "clean": "script/clean.bash",
-    "format": "prettier --ignore-path ../.gitignore --write \"**/*.{ts,tsx,css,scss}\""
+    "format": "prettier --ignore-path ../.gitignore --write \"**/*.{ts,tsx,css,scss}\"",
+    "graph": "script/graph.bash"
   },
   "eslintConfig": {
     "extends": [

client/script/clean.bash

@@ -1,2 +1,3 @@
 #!/bin/bash
-rm -rf build/ node_modules/ coverage/ playwright-report/
+rm -rf build/ node_modules/ coverage/ playwright-report/
+rm src.svg test.svg

client/script/graph.bash

@@ -0,0 +1,7 @@
+#!/bin/bash
+PATH="$(yarn bin):$PATH"
+export PATH
+printf "Generate dependency graph for code"
+
+madge --image src.svg src
+madge --image test.svg test

deploy/README.md

@@ -114,4 +114,4 @@ You can run this script multiple times until the installation is successful.
 
 ## Access the application
 
-Now you should be able to access the DTaaS application at: <http:>_https://foo.com_</http:>
+Now you should be able to access the DTaaS application at: _https://foo.com_

docs/FAQ.md

@@ -1,3 +1,4 @@
+# Frequently Asked Questions
 
 ## Abreviations
 
@@ -40,7 +41,8 @@
     DTaaS is not a model creation  tool. You can put model creation tool
     inside DTaaS and create new models.
 
-    The DTaaS itself does not create digital twin models. But you can run
+    The DTaaS itself does not create digital twin models but it can help
+    users create digital twin models. You can run
     Linux desktop / terminal tools  inside the DTaaS. So you can create
     models inside DTaaS and run them using tools that can run in Linux.
     The Windows only tools can not run in DTaaS.
@@ -74,8 +76,9 @@
     to provide one.
 
 ??? Question "Does it support XML-based representation and ontology representation?"
-    Currently No. **We are looking for users needing this capability. If you have concrete requirements and an example, we can discuss a way of realizing it in DTaaS**. 
-
+    Currently No. **We are looking for users needing this capability.**
+    **If you have concrete requirements and an example, we can discuss a way**
+    **of realizing it in DTaaS**.
 
 ## Communication Between Physical Twin and Digital Twin
 

docs/admin/services.md

@@ -0,0 +1,128 @@
+# :electric_plug: Third-party Services
+
+The DTaaS software platform uses third-party software services
+to provide enhanced value to users.
+
+InfluxDB, RabbitMQ and Grafana are default services
+integrated into the DTaaS software platform.
+
+_The InfluxDB service requires a dedicated hostname. The management
+interface of RabbitMQ service requires a dedicated hostname as well._
+
+Thus successful installation of these services
+is dependent on your ability to use
+multiple hostnames for different services. You can download the required
+services using the docker commands.
+
+```sh
+docker pull traefik:v2.5
+docker pull influxdb:2.4
+docker pull mltooling/ml-workspace:0.13.2
+docker pull grafana/grafana
+docker pull gitlab/gitlab-ce:15.10.0-ce.0
+```
+
+:warning: The docker images are large and are likely to consume
+about 5GB of bandwidth and 15GB of space.
+You will have to download the docker images on a really good network.
+
+The two-machine vagrant deployment scenario installs the RabbitMQ, Grafana, and
+InfluxDB services on the second vagrant machine.
+
+If you would like to install some of these services for native OS
+installation or single vagrant machine, you can do this as well.
+
+## RabbitMQ Service
+
+Start the RabbitMQ service with
+
+```bash
+docker run -d \
+ --name rabbitmq-server \
+ -p 15672:15672 -p 5672:5672 \
+ rabbitmq:3-management
+```
+
+Users and the vhosts need to be setup on the server. Sample commands to do so are:
+
+```bash
+docker exec rabbitmq-server rabbitmqctl add_user <username> <password>
+docker exec rabbitmq-server rabbitmqctl set_permissions -p "/<vhost>" <username> ".*" ".*" ".*"
+```
+
+The RabbitMQ service requires raw TCP/UDP protocol access to network.
+The default Traefik configuration of DTaaS does not permit TCP/UDP traffic. There are two possible choices here:
+
+* Configure Traefik gateway to permit TCP/UDP traffic
+* Bypass Traefik altogether for RabbitMQ service
+
+Unless you are an informed user of Traefik, we recommend bypassing traefik
+for RabbitMQ service.
+
+## Grafana Service
+
+Grafana service can run well behind Traefik gateway. Here is a sample docker
+command to run Grafana service at port 3000:
+
+```bash
+docker run -d \
+ -p 3000:3000 \
+ --name=grafana \
+ -e "GF_SERVER_SERVE_FROM_SUB_PATH=true" \
+ -e "GF_SERVER_DOMAIN=localhost" \
+ -e "GF_SERVER_ROOT_URL=%(protocol)s://%(domain)s:%(http_port)s" \
+ -e "GF_AUTH_BASIC_ENABLED=false" \
+ -e "GF_AUTH_PROXY_ENABLED=false" \
+ -e "GF_SECURITY_ADMIN_PASSWORD=DTaaSGrafana" \
+ -e "GF_SECURITY_ALLOW_EMBEDDING=true" \
+ -e "GF_SECURITY_ALLOW_EMBEDDING=true" \
+ -e "GF_AUTH_ANONYMOUS_ENABLED=true" \
+ -e "GF_AUTH_ANONYMOUS_ORG_NAME=Main" \
+ -e "GF_AUTH_ANONYMOUS_ORG_ROLE=Editor" \
+ -e "GF_USERS_ALLOW_SIGN_UP=false" \
+ -e "GF_FEATURE_TOGGLES_ENABLE=publicDashboards" \
+ -e "GF_PATHS_CONFIG=/etc/grafana/grafana.ini"  \
+ -e "GF_PATHS_DATA=/var/lib/grafana" \
+ -e "GF_PATHS_HOME=/usr/share/grafana" \
+ -e "GF_PATHS_LOGS=/var/log/grafana" \
+ -e "GF_PATHS_PLUGINS=/var/lib/grafana/plugins" \
+ -e "GF_PATHS_PROVISIONING=/etc/grafana/provisioning" \
+ -e "HOME=/home/grafana" \
+ grafana/grafana
+printf "Complete the setup from GUI"
+```
+
+The user credentials have also been set in the command as:
+
+**username**: admin  
+**password**: DTaaSGrafana
+
+Remember to change these credentials before starting the docker container.
+
+## InfluxDB Service
+
+The barebones InfluxDB service can be installed using:
+
+```bash
+INFLUXDB_DATA="${PWD}/data/influxdb2"
+mkdir -p "$INFLUXDB_DATA"
+
+# Remember to change the settings
+docker run -d -p 80:8086 \
+  --name influxdb24 \
+  -v "$INFLUXDB_DATA/data":/var/lib/influxdb2 \
+  -v "$INFLUXDB_DATA/config":/etc/influxdb2 \
+  -e DOCKER_INFLUXDB_INIT_MODE=setup \
+  -e DOCKER_INFLUXDB_INIT_USERNAME=dtaas \
+  -e DOCKER_INFLUXDB_INIT_PASSWORD=dtaas1357 \
+  -e DOCKER_INFLUXDB_INIT_ORG=dtaas \
+  -e DOCKER_INFLUXDB_INIT_BUCKET=dtaas \
+  influxdb:2.4
+```
+
+The user credentials have also been set in the command as:
+
+**username**: dtaas  
+**password**: dtaas1357
+
+Remember to change these credentials before starting the docker container.