Merge branch 'INTO-CPS-Association:feature/distributed-demo' into fea…

…ture/distributed-demo

docs/FAQ.md

@@ -210,4 +210,21 @@
     that GE Predix natively provides in one interface.
     The takeaway is that we pick horses for the courses.
 
+## Create Assets
+
+??? Question "Can DTaaS be used to create new DT assets?"
+
+    The core feature of DTaaS software is to help users
+    create DTs from assets already available in the library.
+
+    ![Create Library Assets](./user/servers/lib/author.png)
+
+    However, it is possible for users to take advantage of services
+    available in their workspace to install asset authoring tools
+    in their own workspace.
+    These authoring tools can then be used to create and publish new assets.
+    User workspaces are private and are not shared with other users.
+    Thus any licensed software tools installed in their workspace is
+    only available to them.
+
 <!-- markdownlint-enable MD046 -->

docs/admin/host.md

@@ -9,17 +9,26 @@ A dummy **foo.com** URL has been used for illustration.
 Please change this to your unique website URL.
 It is assumed that you are going to serve the application in only HTTPS mode.
 
+A successful installation will create a setup
+similar to the one shown in the figure.
+
+![Single host install](./single-host.png)
+
 Please follow these steps to make this work in your local environment.
 Download the **DTaaS.zip** from the
 [releases page](https://github.com/INTO-CPS-Association/DTaaS/releases).
 Unzip the same into a directory named **DTaaS**.
 The rest of the instructions assume that your working directory is **DTaaS**.
 
+<!-- markdownlint-disable MD046 -->
+
 !!! note
     If you only want to test the application
     and are not setting up a production instance,
     you can follow the instructions of [trial installation](trial.md).
 
+<!-- markdownlint-enable MD046 -->
+
 ## Configuration
 
 You need to configure the Traefik gateway,
@@ -40,10 +49,14 @@ at _deploy/config/gateway/fileConfig.yml_.
 Change `foo.com` to your local hostname and user1/user2 to
 the usernames chosen by you.
 
+<!-- markdownlint-disable MD046 -->
+
 !!! tip
     Do not use `http://` or `https://`
     in _deploy/config/gateway/fileConfig.yml_.
 
+<!-- markdownlint-enable MD046 -->
+
 #### Authentication
 
 This step requires `htpasswd` commandline utility. If
@@ -154,3 +167,12 @@ 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:>
+
+## References
+
+Image sources: [Ubuntu logo](https://logodix.com/linux-ubuntu),
+[Traefik logo](https://www.laub-home.de/wiki/Traefik_SSL_Reverse_Proxy_f%C3%BCr_Docker_Container),
+[ml-workspace](https://github.com/ml-tooling/ml-workspace),
+[nodejs](https://www.metachris.com/2017/01/how-to-install-nodejs-7-on-ubuntu-and-centos/),
+[reactjs](https://krify.co/about-reactjs/),
+[nestjs](https://camunda.com/blog/2019/10/nestjs-tx-email/)

docs/admin/overview.md

@@ -14,6 +14,22 @@ 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).
 
+### Domain name
+
+The DTaaS software can only be hosted on a server with a domain name
+like <http:>_foo.com_</http:>.
+
+### Reverse Proxy
+
+The installation setup assumes that the foo.com server is behind a reverse
+proxy / load balancer that provides https termination. You can still use
+the DTaaS software even if you do not have this reverse proxy. If you do
+not have a reverse proxy, please replace <http:>_https://foo.com_</http:>
+with <http:>_http://foo.com_</http:> in
+[client .env file](./client/CLIENT.md) and in
+[OAuth registration](./client/auth.md). Other installation configuration
+remains the same.
+
 ## What to install
 
 The DTaaS can be installed in different ways. Each version is for different purposes:

docs/admin/servers/lib/LIB-MS.md

@@ -5,7 +5,8 @@ It has three features:
 
 * provide a listing of directory contents.
 * transfer a file to user.
-* Source files can either come from local file system or from a gitlab instance.
+* Source files can either come from local file system or from
+  a gitlab instance.
 
 The library microservice is designed to manage and serve files,
 functions, and models to users, allowing them to access and interact

docs/admin/trial.md

@@ -1,8 +1,15 @@
 # Trial Installation
 
-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
+To try out the software, you can install it on Ubuntu Server 22.04
+Operating System.  The setup requires a
+machine which can spare 16GB RAM, 8 vCPUs and 50GB Hard Disk
+space to the vagrant box.
+A successful installation will create a setup
+similar to the one shown in the figure.
+
+![Single host install](./single-host.png)
+
+A one-step installation script is provided on this page. This script sets up
 the DTaaS software with default credentials and users.
 You can use it to check a test installation of DTaaS software.
 
@@ -57,3 +64,12 @@ to your local settings in the following files.
 
 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.
+
+## References
+
+Image sources: [Ubuntu logo](https://logodix.com/linux-ubuntu),
+[Traefik logo](https://www.laub-home.de/wiki/Traefik_SSL_Reverse_Proxy_f%C3%BCr_Docker_Container),
+[ml-workspace](https://github.com/ml-tooling/ml-workspace),
+[nodejs](https://www.metachris.com/2017/01/how-to-install-nodejs-7-on-ubuntu-and-centos/),
+[reactjs](https://krify.co/about-reactjs/),
+[nestjs](https://camunda.com/blog/2019/10/nestjs-tx-email/)

docs/admin/vagrant/base-box.md

@@ -33,18 +33,13 @@ are not a developer, no changes are required to the `Vagrantfile`.
 
 This vagrant box installed for users will have the following items:
 
-* docker v24.0
-* nodejs v18.8
-* yarn v1.22
-* npm v10.2
-* containers
-  * ml-workspace v0.13
-  * traefik v2.10
-  * gitlab-ce v16.4
-  * influxdb v2.7
-  * grafana v10.1
-  * rabbitmq v3-management
-  * eclipse-mosquitto (mqtt) v2
+1. docker v24.0
+1. nodejs v18.8
+1. yarn v1.22
+1. npm v10.2
+1. containers - ml-workspace v0.13, traefik v2.10, gitlab-ce v16.4,
+   influxdb v2.7, grafana v10.1, rabbitmq v3-management,
+   eclipse-mosquitto (mqtt) v2
 
 This vagrant box installed for developers will have
 the following items additional items:
@@ -53,8 +48,13 @@ the following items additional items:
 * microk8s v1.27
 * jupyterlab
 * mkdocs
-* containers
-  * telegraf v1.28
+* container - telegraf v1.28
+
+At the end of installation, the software stack created
+in vagrant box can be visualised as shown in the following
+figure.
+
+![vagrant base box](./basebox.png)
 
 The upcoming instructions will help with the creation of
 base vagrant box.
@@ -100,3 +100,7 @@ vagrant box add --name dtaas ./dtaas.vagrant
 # You can use this box in other vagrant boxes using
 #config.vm.box = "dtaas"
 ```
+
+## References
+
+Image sources: [Ubuntu logo](https://logodix.com/linux-ubuntu)

docs/admin/vagrant/single-machine.md

@@ -1,29 +1,64 @@
 # DTaaS on Single Vagrant Machine
 
-These are installation instructions for running DTaaS application
-inside one vagrant Virtual Machine.  The setup requires a
+These are installation instructions for running DTaaS software
+inside one vagrant Virtual Machine. The setup requires a
 machine which can spare 16GB RAM, 8 vCPUs and 50GB Hard Disk
 space to the vagrant box.
 
+## Create Base Vagrant Box
+
+Create [**dtaas** Vagrant box](./base-box.md).
+You would have created an SSH key pair - _vagrant_ and _vagrant.pub_.
+The _vagrant_ is the private SSH key and is needed for the next steps.
+Copy _vagrant_ SSH private key into the current directory
+(`deploy/vagrant/single-machine`).
+This shall be useful for logging into the vagrant
+machines created for two-machine deployment.
+
+## Target Installation Setup
+
+The goal is to use the [**dtaas** Vagrant box](./base-box.md)
+to install the DTaaS software on one single vagrant machine.
+A graphical illustration of a successful installation can be
+seen here.
+
+![Single vagrant machine](./single-machine.png)
+
+There are many unused software packages/docker containers within
+the dtaas base box.
+The used packages/docker containers are highlighed in blue color.
+
+<!-- markdownlint-disable MD046 -->
+
+!!! tip
+    The illustration shows hosting of gitlab on the same
+    vagrant machine with <http:>_http(s)://gitlab.foo.com_</http:>
+    The gitlab setup is outside the scope this installation
+    guide. Please refer to
+    [gitlab docker install](https://docs.gitlab.com/ee/install/docker.html)
+    for gitlab installation.
+
+<!-- markdownlint-enable MD046 -->
+
+## Configure Server Settings
+
 A dummy **foo.com** URL has been used for illustration.
 Please change this to your unique website URL.
 
-Please follow these steps to make this work in your local environment.
-
-1. Create [**dtaas** Vagrant box](./base-box.md).
-   You would have created an SSH key pair - _vagrant_ and
-   _vagrant.pub_ for the vagrant box.
-   The _vagrant_ is the private SSH key; Copy _vagrant_ SSH private key into
-   the current directory (`deploy/vagrant/single-machine`).
-   This shall be useful for logging into the vagrant
-   machine created for single-machine deployment.
-1. Update the **Vagrantfile**. Fields to update are:
-    1. Hostname (`node.vm.hostname = "foo.com"`)
-    1. MAC address (`:mac => "xxxxxxxx"`).
-    This change is required if you have a DHCP server assigning domain names
-    based on MAC address. Otherwise, you can leave this field unchanged.
-    1. Other adjustments are optional.
-1. Execute the following commands from terminal
+Please follow the next steps to make this installation work
+in your local environment.
+
+Update the **Vagrantfile**. Fields to update are:
+
+1. Hostname (`node.vm.hostname = "foo.com"`)
+1. MAC address (`:mac => "xxxxxxxx"`).
+   This change is required if you have a DHCP server assigning domain names
+   based on MAC address. Otherwise, you can leave this field unchanged.
+1. Other adjustments are optional.
+
+## Installation Steps
+
+Execute the following commands from terminal
 
 ```bash
 vagrant up
@@ -45,3 +80,12 @@ follow the instructions of [single script install](../trial.md).
 If you are not in a hurry and would rather have a production
 instance, follow the instructions of [regular server installation](../host.md)
 setup to complete the installation.
+
+## References
+
+Image sources: [Ubuntu logo](https://logodix.com/linux-ubuntu),
+[Traefik logo](https://www.laub-home.de/wiki/Traefik_SSL_Reverse_Proxy_f%C3%BCr_Docker_Container),
+[ml-workspace](https://github.com/ml-tooling/ml-workspace),
+[nodejs](https://www.metachris.com/2017/01/how-to-install-nodejs-7-on-ubuntu-and-centos/),
+[reactjs](https://krify.co/about-reactjs/),
+[nestjs](https://camunda.com/blog/2019/10/nestjs-tx-email/)

docs/admin/vagrant/two-machines.md

@@ -12,7 +12,7 @@ The setup requires two server VMs with the following hardware configuration:
 
 Under the default configuration, two user workspaces are provisioned on server1.
 The default installation setup also installs
-InfluxDB, Grafana and RabbitMQ services on server2.
+InfluxDB, Grafana, RabbitMQ and MQTT services on server2.
 If you would like to install more services,
 you can create shell scripts to install the same on server2.
 
@@ -21,13 +21,43 @@ you can create shell scripts to install the same on server2.
 Create [**dtaas** Vagrant box](./base-box.md).
 You would have created an SSH key pair - _vagrant_ and _vagrant.pub_.
 The _vagrant_ is the private SSH key and is needed for the next steps.
-Copy _vagrant_ SSH private key into the current directory (`deploy/vagrant/single-machine`).
+Copy _vagrant_ SSH private key into the current directory (`deploy/vagrant/two-machine`).
 This shall be useful for logging into the vagrant
 machines created for two-machine deployment.
 
+## Target Installation Setup
+
+The goal is to use this [**dtaas** vagrant box](./base-box.md)
+to install the DTaaS software on server1 and
+the default platform services on server2. Both the servers
+are vagrant machines.
+
+![DTaaS vagrant box package use](./two-machine-use-legend.png)
+
+There are many unused software packages/docker containers within
+the dtaas base box.
+The used packages/docker containers are highlighed in blue and red color.
+
+A graphical illustration of a successful installation can be
+seen here.
+
+![Two vagrant machine](./two-machine.png)
+
+In this case, both the vagrant boxes are spawed on one server using
+two vagrant configuration files, namely _boxes.json_ and _Vagrantfile_.
+
+!!! tip
+    The illustration shows hosting of gitlab on the same
+    vagrant machine with <http:>_http(s)://gitlab.foo.com_</http:>
+    The gitlab setup is outside the scope this installation
+    guide. Please refer to
+    [gitlab docker install](https://docs.gitlab.com/ee/install/docker.html)
+    for gitlab installation.
+
 ## Configure Server Settings
 
-**NOTE**: A dummy **foo.com** and **services.foo.com**  URLs has been used for illustration.
+**NOTE**: A dummy **foo.com** and **services.foo.com**  URLs
+has been used for illustration.
 Please change these to your unique website URLs.
 
 The first step is to define the network identity of the two VMs.
@@ -50,13 +80,16 @@ The fields to update are:
      names based on MAC address. Otherwise, you can leave this field unchanged.
   1. Other adjustments are optional.
 
-## Launch platform default services
+## Installation Steps
+
+### Launch DTaaS Platform Default Services
 
-RabbitMQ, Grafana and InfluxDB services are provisioned on this server.
+RabbitMQ, Grafana, InfluxDB and MQTT services are provisioned on this server.
 InfluxDB and visualization service will be available at: _services.foo.com_.
+The Grafana service shall be available at TCP port 3000.
+The MQTT service shall be available at TCP port 1833.
 The RabbitMQ service and its management interface shall be available at
 5672 and 15672 TCP ports respectively.
-The Grafana service shall be available at TCP port 3000.
 
 The firewall and network access settings of corporate / cloud network
 need to be configured to allow external access to the services.
@@ -81,11 +114,11 @@ you can see the following services active within server2.
 |:---|:---|
 | InfluxDB and visualization service | services.foo.com |
 | Grafana visualization service | services.foo.com:3000 |
+| MQTT communication service | services.foo.com:1883 |
 | RabbitMQ communication service | services.foo.com:5672 |
 | RabbitMQ management service | services.foo.com:15672 |
-||
 
-## Launch DTaaS application
+### Install DTaaS Application
 
 Execute the following commands from terminal
 
@@ -103,3 +136,12 @@ follow the instructions of [single script install](../trial.md).
 If you are not in a hurry and would rather have a production instance,
 follow the instructions of [regular server installation](../host.md)
 setup to complete the installation.
+
+## References
+
+Image sources: [Ubuntu logo](https://logodix.com/linux-ubuntu),
+[Traefik logo](https://www.laub-home.de/wiki/Traefik_SSL_Reverse_Proxy_f%C3%BCr_Docker_Container),
+[ml-workspace](https://github.com/ml-tooling/ml-workspace),
+[nodejs](https://www.metachris.com/2017/01/how-to-install-nodejs-7-on-ubuntu-and-centos/),
+[reactjs](https://krify.co/about-reactjs/),
+[nestjs](https://camunda.com/blog/2019/10/nestjs-tx-email/)