diff --git a/docs/FAQ.md b/docs/FAQ.md index 305926606..b22d56fa1 100644 --- a/docs/FAQ.md +++ b/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. + diff --git a/docs/admin/host.md b/docs/admin/host.md index 318bf732f..71a90a23d 100644 --- a/docs/admin/host.md +++ b/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**. + + !!! 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). + + ## 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. + + !!! tip Do not use `http://` or `https://` in _deploy/config/gateway/fileConfig.yml_. + + #### 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: _https://foo.com_ + +## 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/) diff --git a/docs/admin/overview.md b/docs/admin/overview.md index cfaf7aa0c..2b0fca10a 100644 --- a/docs/admin/overview.md +++ b/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 _foo.com_. + +### 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 _https://foo.com_ +with _http://foo.com_ 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: diff --git a/docs/admin/servers/lib/LIB-MS.md b/docs/admin/servers/lib/LIB-MS.md index 301ef2a66..8cee47ae5 100644 --- a/docs/admin/servers/lib/LIB-MS.md +++ b/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 diff --git a/docs/admin/single-host.png b/docs/admin/single-host.png new file mode 100644 index 000000000..5211b132c Binary files /dev/null and b/docs/admin/single-host.png differ diff --git a/docs/admin/trial.md b/docs/admin/trial.md index 84ce1f8cd..39dc168be 100644 --- a/docs/admin/trial.md +++ b/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/) diff --git a/docs/admin/vagrant/base-box.md b/docs/admin/vagrant/base-box.md index 23ffccd42..cece92ac9 100644 --- a/docs/admin/vagrant/base-box.md +++ b/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) \ No newline at end of file diff --git a/docs/admin/vagrant/basebox.png b/docs/admin/vagrant/basebox.png new file mode 100644 index 000000000..360b9f189 Binary files /dev/null and b/docs/admin/vagrant/basebox.png differ diff --git a/docs/admin/vagrant/single-machine.md b/docs/admin/vagrant/single-machine.md index f72852647..9d068ad1e 100644 --- a/docs/admin/vagrant/single-machine.md +++ b/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. + + + +!!! tip + The illustration shows hosting of gitlab on the same + vagrant machine with _http(s)://gitlab.foo.com_ + 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 + 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/) diff --git a/docs/admin/vagrant/single-machine.png b/docs/admin/vagrant/single-machine.png new file mode 100644 index 000000000..6de845acd Binary files /dev/null and b/docs/admin/vagrant/single-machine.png differ diff --git a/docs/admin/vagrant/two-machine-use-legend.png b/docs/admin/vagrant/two-machine-use-legend.png new file mode 100644 index 000000000..e59534b16 Binary files /dev/null and b/docs/admin/vagrant/two-machine-use-legend.png differ diff --git a/docs/admin/vagrant/two-machine.png b/docs/admin/vagrant/two-machine.png new file mode 100644 index 000000000..21f716153 Binary files /dev/null and b/docs/admin/vagrant/two-machine.png differ diff --git a/docs/admin/vagrant/two-machines.md b/docs/admin/vagrant/two-machines.md index 532dde224..f9332b89d 100644 --- a/docs/admin/vagrant/two-machines.md +++ b/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(s)://gitlab.foo.com_ + 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/) diff --git a/docs/developer/system/DTaaS.drawio b/docs/developer/system/DTaaS.drawio index 220503f54..fbc1a6f5a 100644 --- a/docs/developer/system/DTaaS.drawio +++ b/docs/developer/system/DTaaS.drawio @@ -1,6 +1,6 @@ - + - + @@ -979,7 +979,7 @@ - + @@ -1550,17 +1550,17 @@ - + - + - + @@ -1572,7 +1572,7 @@ - + @@ -1584,12 +1584,12 @@ - + - + @@ -1598,7 +1598,7 @@ - + @@ -1606,7 +1606,7 @@ - + @@ -2740,4 +2740,623 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/developer/testing/intro.md b/docs/developer/testing/intro.md index b90d1bfdd..b8ed9f267 100644 --- a/docs/developer/testing/intro.md +++ b/docs/developer/testing/intro.md @@ -45,8 +45,13 @@ the concepts of BDD. ## :building_construction: Testing workflow -We follow a testing workflow in accordance with -[The Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html#TheTestPyramid), +![Gitlab signin button](testPyramid.png) + +(Ref: Ham Vocke, +[The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)) + +We follow a testing workflow in accordance with the test pyramid diagram +given above, starting with isolated tests and moving towards complete integration for any new feature changes. The different types of tests (in the order that they should be performed) are explained below: @@ -114,3 +119,12 @@ Hence feature tests prove to be useful. The DTaaS project does not have any feature tests yet. [Cucumber](https://github.com/cucumber/cucumber-js) shall be used in future to implement feature tests. + +## References + +Justin Searls and Kevin Buchanan, +[Contributing Tests wiki](https://github.com/testdouble/contributing-tests/wiki). +This wiki has goog explanation of +[TDD](https://github.com/testdouble/contributing-tests/wiki/Test-Driven-Development) +and +[test doubles](https://github.com/testdouble/contributing-tests/wiki/Test-Double). diff --git a/docs/developer/testing/testPyramid.png b/docs/developer/testing/testPyramid.png new file mode 100644 index 000000000..0bb37d205 Binary files /dev/null and b/docs/developer/testing/testPyramid.png differ diff --git a/docs/user/digital-twins/lifecycle.md b/docs/user/digital-twins/lifecycle.md index 9b70fb41d..3bc5f2719 100644 --- a/docs/user/digital-twins/lifecycle.md +++ b/docs/user/digital-twins/lifecycle.md @@ -12,6 +12,11 @@ are illustrated in the figure. ![DT-PT Lifecycle](lifecycle-four-stages.png) +(Ref: Minerva, R, Lee, GM and Crespi, N (2020) Digital Twin +in the IoT context: a survey on technical features, scenarios +and architectural models. Proceedings of the IEEE, 108 (10). +pp. 1785-1824. ISSN 0018-9219.) + ## Lifecycle Phases The four phase lifecycle has been extended to a lifecycle with @@ -71,7 +76,7 @@ A dedicated program exists for each phase of DT lifecycle. Each program can be as simple as a script that launches other programs or sends messages to a live digital twin. -## Examples +## Example Lifecycle Scripts Here are the example programs / scripts to manage three phases in the lifecycle of **mass-spring-damper DT**. diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 71462cf8a..77475805c 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -9,16 +9,12 @@ digital twins within the platform. 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 +Use the given shell script 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 +wget https://raw.githubusercontent.com/INTO-CPS-Association/DTaaS-examples/main/getExamples.sh +bash getExamples.sh ``` ## Example List diff --git a/docs/user/features.md b/docs/user/features.md index 863064ca9..c36dbdafa 100644 --- a/docs/user/features.md +++ b/docs/user/features.md @@ -7,9 +7,9 @@ The DTaaS software platform provides certain advantages to users: * Support for different kinds of Digital Twins * CFD, Simulink, co-simulation, FEM, ROM, ML etc. * Integrates with other Digital Twin frameworks -* Facilitate availability of Digital Twin as a service +* Facilitate availability of Digital Twin as a Service * Collaboration and reuse -* Private workspaces for authoring and verification +* Private workspaces for verification of reusable assets, trial run DTs * Cost effectiveness @@ -52,7 +52,7 @@ The currently available services are: | MQTT | Lightweight data transfer broker for IoT devices / physical twins feeding data into digital twins. | In addition, the workspaces are connected to the Internet so -all the Digital Twins run within their workspace can interact +all the Digital Twins running in the workspace can interact with both the internal and external services. The users can publish and reuse the digital twin assets diff --git a/docs/user/motivation.md b/docs/user/motivation.md index f7c573b24..95f309f12 100644 --- a/docs/user/motivation.md +++ b/docs/user/motivation.md @@ -30,6 +30,6 @@ this problem. Some of them are: * Support for transition from existing workflows to DT frameworks * Create DTs from reusable assets * Enable users to share DT assets -* Offer DTs as a service +* Offer DTs as a Service * Integrate the DTs with external software systems * Separate configurations of independent DT components diff --git a/docs/user/servers/lib/assets.md b/docs/user/servers/lib/assets.md index bbf38a137..cc47ffc76 100644 --- a/docs/user/servers/lib/assets.md +++ b/docs/user/servers/lib/assets.md @@ -136,18 +136,6 @@ A recommended file system structure for storing assets is also available in [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples). -## Create Assets - -The DTaaS software allows users to create new library assets on the platform. - -![Create Library Assets](author.png) - -Users can 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. - ## Upload Assets Users can upload assets into their workspace using Library page of the website. @@ -161,3 +149,16 @@ You can also create new assets on the page by clicking on **new** drop down menu. This is a simple web interface which allows you to create text-based files. You need to upload other files using **upload** button. + +The user workbench has the following services: + +* Jupyter Notebook and Lab +* VS Code +* XFCE Desktop Environment available via VNC +* Terminal + +Users can also bring their DT assets into user workspaces from outside +using any of the above mentioned services. The developers using _git_ +repositories can clone from and push to remote git servers. Users can +also use widely used file transfer protocols such as FTP, and SCP to +bring the required DT assets into their workspaces. diff --git a/docs/user/website/gitlab-sso-1.png b/docs/user/website/gitlab-sso-1.png new file mode 100644 index 000000000..7e2c7790c Binary files /dev/null and b/docs/user/website/gitlab-sso-1.png differ diff --git a/docs/user/website/gitlab-sso-2.png b/docs/user/website/gitlab-sso-2.png new file mode 100644 index 000000000..6b89c9a3e Binary files /dev/null and b/docs/user/website/gitlab-sso-2.png differ diff --git a/docs/user/website/gitlab-sso-3.png b/docs/user/website/gitlab-sso-3.png new file mode 100644 index 000000000..ec0338db8 Binary files /dev/null and b/docs/user/website/gitlab-sso-3.png differ diff --git a/docs/user/website/index.md b/docs/user/website/index.md index cda1291d8..bbfbf6d49 100644 --- a/docs/user/website/index.md +++ b/docs/user/website/index.md @@ -8,15 +8,39 @@ the DTaaS software platform. ![Login](login.png) The screen presents with HTTP authentication form. You can enter the user -credentials. You will be using HTTPS secure communication so the username -and password are secure. +credentials. If the DTaaS is being served over HTTPS secure communication +protocol, the username and password are secure. -## Enter username again +## Start the Authentication -![Username](username.png) +You are now logged into the DTaaS server. The DTaaS uses third-party authentication +protocol known as +[OAuth](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce). +This protocol provides secure access to a DTaaS +installation if users have a working active accounts at the selected OAuth +service provider. The DTaaS uses Gitlab as OAuth provider. -You are now logged into the server. You can enter the same username again -to log into your workspace. +![Gitlab signin button](gitlab-sso-1.png) + +You can see the Gitlab signin button. A click on this button takes you to +Gitlab instance providing authentication for DTaaS. + +## Authenticate at Gitlab + +The username and password authentication takes place on the gitlab website. +Enter your username and password in the login form. + +![Gitlab login form](gitlab-sso-2.png) + +## Permit DTaaS to Use Gitlab + +The DTaaS application needs your permission to use your Gitlab account for +authentication. Click on **Authorize** button. + +![Gitlab OAuth permission](gitlab-sso-3.png) + +After successful authentication, you will be redirected to the **Library** +page of the DTaaS website. ## Overview of menu items