From 84baabe114d12eecdb27fe24cbf06b1ab1a58958 Mon Sep 17 00:00:00 2001 From: Astitva Sehgal <69433630+astitva1905@users.noreply.github.com> Date: Tue, 3 Oct 2023 13:53:38 +0530 Subject: [PATCH] Rectifies .mdlrc and resolves markdown linting Issues (#122) --- .mdl_style.rb | 6 +- LICENSE.md | 197 ++++++++------ client/LICENSE.md | 197 ++++++++------ client/README.md | 49 +++- client/test/README.md | 81 ++++-- deploy/README.md | 2 +- deploy/vagrant/make_boxes/dtaas/README.md | 22 +- deploy/vagrant/single-machine/README.md | 10 +- deploy/vagrant/two-machine/README.md | 48 +++- docs/FAQ.md | 270 ++++++++++---------- docs/LICENSE.md | 209 ++++++++------- docs/PUBLISH.md | 4 +- docs/admin/client/CLIENT.md | 155 +++++------ docs/admin/client/auth.md | 59 ++++- docs/admin/servers/lib/LIB-MS.md | 38 ++- docs/admin/services.md | 7 +- docs/admin/trial.md | 1 - docs/developer/index.md | 59 +++-- docs/developer/servers/lib/lib-ms.md | 4 +- docs/developer/system/architecture.md | 77 +++--- docs/developer/system/current-status.md | 2 +- docs/developer/testing/intro.md | 29 ++- docs/index.md | 20 +- docs/thanks.md | 8 +- docs/user/digital-twins/create.md | 46 ++-- docs/user/digital-twins/lifecycle.md | 5 +- docs/user/examples/incubator/README.md | 37 ++- docs/user/examples/index.md | 2 + docs/user/features.md | 37 ++- docs/user/motivation.md | 3 +- docs/user/servers/lib/LIB-MS.md | 152 ++++++----- docs/user/servers/lib/assets.md | 86 +++++-- docs/user/website/index.md | 23 +- servers/config/gateway/README.md | 4 +- servers/execution/runner/LICENSE.md | 210 +++++++++------ servers/execution/runner/README.md | 26 +- servers/lib/LICENSE.md | 193 ++++++++------ servers/lib/README.md | 12 +- servers/lib/test/README.md | 6 +- servers/lib/test/data/user2/tools/README.md | 2 + ssl/README.md | 18 +- 41 files changed, 1423 insertions(+), 993 deletions(-) diff --git a/.mdl_style.rb b/.mdl_style.rb index ba34fb48e..015105071 100644 --- a/.mdl_style.rb +++ b/.mdl_style.rb @@ -1,4 +1,4 @@ all -rule 'MD013', :ignore_code_blocks => true -rule 'MD013', :tables => false -rule 'MD046', :indented => true +exclude_rule 'MD033' +rule 'MD013', :code_blocks => false, :tables => false +rule 'MD046', :style => :fenced diff --git a/LICENSE.md b/LICENSE.md index be60b871f..c0ad1333c 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,74 +1,85 @@ +# License + --- Start of Definition of INTO-CPS Association Public License --- /* - * This file is part of the INTO-CPS Association. - * - * Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), - * c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, - * Finlandsgade 22, 8200 Aarhus N, Denmark. - * - * All rights reserved. - * - * THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR - * THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. - * ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES - * RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR - * THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. - * - * The INTO-CPS tool suite software and the INTO-CPS Association - * Public License (ICAPL) are obtained from the INTO-CPS Association, either - * from the above address, from the URLs: http://www.into-cps.org or - * in the INTO-CPS tool suite distribution. - * GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. - * - * This program is distributed WITHOUT ANY WARRANTY; without - * even the implied warranty of MERCHANTABILITY or FITNESS - * FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH - * IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF - * THE INTO-CPS ASSOCIATION PUBLIC LICENSE. - * - * See the full ICAPL conditions for more details. - * + +* This file is part of the INTO-CPS Association. + +* Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), +* c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, +* Finlandsgade 22, 8200 Aarhus N, Denmark. + +* All rights reserved. + +* THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR +* THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. +* ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES +* RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR +* THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. + +* The INTO-CPS tool suite software and the INTO-CPS Association +* Public License (ICAPL) are obtained from the INTO-CPS Association, either +* from the above address, from the URLs: http://www.into-cps.org or +* in the INTO-CPS tool suite distribution. +* GNU version 3 is obtained from: +* http://www.gnu.org/copyleft/gpl.html. + +* This program is distributed WITHOUT ANY WARRANTY; without +* even the implied warranty of MERCHANTABILITY or FITNESS +* FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH +* IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF +* THE INTO-CPS ASSOCIATION PUBLIC LICENSE. + +* See the full ICAPL conditions for more details. + */ --- End of INTO-CPS Association Public License Header --- -The ICAPL is a public license for the INTO-CPS tool suite with three modes/alternatives +The ICAPL is a public license for the INTO-CPS tool +suite with three modes/alternatives (GPL, ICA-Internal-EPL, ICA-External-EPL) for use and redistribution, in source and/or binary/object-code form: -* GPL. Any party (member or non-member of the INTO-CPS Association) may use and +* GPL. Any party (member or non-member of the INTO-CPS Association) may use and redistribute INTO-CPS tool suite under GPL version 3. -* Silver Level members of the INTO-CPS Association may also use and redistribute +* Silver Level members of the INTO-CPS Association may also use and redistribute the INTO-CPS tool suite under ICA-Internal-EPL conditions. -* Gold Level members of the INTO-CPS Association may also use and redistribute +* Gold Level members of the INTO-CPS Association may also use and redistribute The INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions. Definitions of the INTO-CPS Association Public license modes: * GPL = GPL version 3. -* ICA-Internal-EPL = These INTO-CPA Association Public license conditions together with - Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association is only allowed - within the INTO-CPS Association member's own organization (i.e., its own legal entity), - or for a member of the INTO-CPS Association paying a membership fee corresponding to - the size of the organization including all its affiliates, use and redistribution - is allowed within/between its affiliates. - -* ICA-External-EPL = These INTO-CPA Association Public license conditions together with - Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association, or by a Licensed - Third Party Distributor having a redistribution agreement with that member, - to parties external to the INTO-CPS Association member’s own organization (i.e., its own - legal entity) is only allowed in binary/object-code form, except the case of - redistribution to other members the INTO-CPS Association to which source is also - allowed to be distributed. +* ICA-Internal-EPL = These INTO-CPA Association Public + license conditions together with + Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association is only allowed + within the INTO-CPS Association member's own + organization (i.e., its own legal entity), + or for a member of the INTO-CPS Association + paying a membership fee corresponding to + the size of the organization including all its affiliates, use and redistribution + is allowed within/between its affiliates. + +* ICA-External-EPL = These INTO-CPA Association Public + license conditions together with + Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association, or by a Licensed + Third Party Distributor having a redistribution agreement with that member, + to parties external to the INTO-CPS Association + member’s own organization (i.e., its own + legal entity) is only allowed in binary/object-code form, except the case of + redistribution to other members the INTO-CPS Association to which source is also + allowed to be distributed. [This has the consequence that an external party who wishes to use -the INTO-CPS Association in source form together with its own proprietary software in all +the INTO-CPS Association in source form together with +its own proprietary software in all cases must be a member of the INTO-CPS Association]. In all cases of usage and redistribution by recipients, the following @@ -90,7 +101,8 @@ c) A recipient must clearly indicate its chosen usage mode of ICAPL, in accompanying documentation and in a text file ICA-USAGE-MODE.txt, provided with the distribution. -d) Contributor(s) making a Contribution to the INTO-CPS Association thereby also makes a +d) Contributor(s) making a Contribution to the + INTO-CPS Association thereby also makes a Transfer of Contribution Copyright. In return, upon the effective date of the transfer, ICA grants the Contributor(s) a Contribution License of the Contribution. ICA has the right to accept or refuse Contributions. @@ -108,38 +120,46 @@ ICA-Internal-EPL and ICA-External-EPL. INTO-CPS Association Public License version 1.0, i.e., the license defined here (the text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of Definition of INTO-CPS Association Public License ---", or later versions thereof. +"--- End of Definition of INTO-CPS Association +Public License ---", or later versions thereof. "ICAPL Header" means: INTO-CPS Association Public License Header version 1.2, i.e., the -text between "--- Start of Definition of INTO-CPS Association Public License ---" and +text between "--- Start of Definition +of INTO-CPS Association Public License ---" and "--- End of INTO-CPS Association Public License Header ---, or later versions thereof. "Contribution" means: -a) in the case of the initial Contributor, the initial code and documentation +a) in the case of the initial Contributor, + the initial code and documentation distributed under ICAPL, and b) in the case of each subsequent Contributor: i) changes to the INTO-CPS tool suite, and ii) additions to the INTO-CPS tool suite; -where such changes and/or additions to the INTO-CPS tool suite originate from and are -distributed by that particular Contributor. A Contribution 'originates' from -a Contributor if it was added to the INTO-CPS tool suite by such Contributor itself or +where such changes and/or additions +to the INTO-CPS tool suite originate from and are +distributed by that particular Contributor. +A Contribution 'originates' from +a Contributor if it was added to the INTO-CPS +tool suite by such Contributor itself or anyone acting on such Contributor's behalf. For Contributors licensing the INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions, the following conditions also hold: Contributions do not include additions to the distributed Program which: (i) -are separate modules of software distributed in conjunction with the INTO-CPS tool suite +are separate modules of software distributed +in conjunction with the INTO-CPS tool suite under their own license agreement, (ii) are separate modules which are not derivative works of the INTO-CPS tool suite, and (iii) are separate modules of software distributed in conjunction with the INTO-CPS tool suite under their own license agreement where these separate modules are merged with (weaved together with) modules of -The INTO-CPS tool suite to form new modules that are distributed as object code or source +The INTO-CPS tool suite to form new modules +that are distributed as object code or source code under their own license agreement, as allowed under the Additional Condition of internal distribution according to ICA-Internal-EPL and/or Additional Condition for external distribution according to ICA-External-EPL. @@ -147,14 +167,22 @@ Additional Condition for external distribution according to ICA-External-EPL. "Transfer of Contribution Copyright" means that the Contributors of a Contribution transfer the ownership and the copyright of the Contribution to the INTO-CPS Association, the INTO-CPS Association Copyright owner, for -inclusion in the INTO-CPS tool suite. The transfer takes place upon the effective date -when the Contribution is made available on the INTO-CPS Association web site under ICAPL, by +inclusion in the INTO-CPS tool suite. +The transfer takes place upon the effective date +when the Contribution is made available on the +INTO-CPS Association web site under ICAPL, by such Contributors themselves or anyone acting on such Contributors' behalf. -The transfer is free of charge. If the Contributors or the INTO-CPS Association so wish, -an optional Copyright transfer agreement can be signed between the INTO-CPS Association and the Contributors. - -"Contribution License" means a license from the INTO-CPS Association to the Contributors of the Contribution, effective on the date of the Transfer of Contribution Copyright, -where the INTO-CPS Association grants the Contributors a non-exclusive, world-wide, transferable, free of charge, perpetual license, including sublicensing rights, to use, +The transfer is free of charge. If the +Contributors or the INTO-CPS Association so wish, +an optional Copyright transfer agreement can be signed +between the INTO-CPS Association and the Contributors. + +"Contribution License" means a license from the INTO-CPS +Association to the Contributors of the Contribution, effective +on the date of the Transfer of Contribution Copyright, +where the INTO-CPS Association grants the Contributors a +non-exclusive, world-wide, transferable, free of charge, +perpetual license, including sublicensing rights, to use, have used, modify, have modified, reproduce and or have reproduced the contributed material, for business and other purposes, including but not limited to evaluation, development, testing, integration and merging with @@ -166,18 +194,19 @@ the INTO-CPS tool chain. "The Program" means the Contributions distributed in accordance with ICAPL. -"The INTO-CPS tool chain" means the Contributions distributed in accordance with ICAPL. +"The INTO-CPS tool chain" means the Contributions +distributed in accordance with ICAPL. "Recipient" means anyone who receives the INTO-CPS tool chain under ICAPL, including all Contributors. "Licensed Third Party Distributor" means a reseller/distributor having signed -a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS -Association Bylaws, with a Gold Level organizational member which is not an -Affiliate of the reseller/distributor, for distributing a product containing -part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall -only be allowed further redistribution to other resellers if the Gold Level -member is granting such a right to it in the redistribution/resale agreement +a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS +Association Bylaws, with a Gold Level organizational member which is not an +Affiliate of the reseller/distributor, for distributing a product containing +part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall +only be allowed further redistribution to other resellers if the Gold Level +member is granting such a right to it in the redistribution/resale agreement between the Gold Level member and the Licensed Third Party Distributor. "Affiliate" shall mean any legal entity, directly or indirectly, through one @@ -197,7 +226,8 @@ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the -appropriateness of using and distributing the INTO-CPS tool suite and assumes all risks +appropriateness of using and distributing the +INTO-CPS tool suite and assumes all risks associated with its exercise of rights under ICAPL , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability @@ -211,16 +241,17 @@ SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL -SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL +SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. A Contributor licensing the INTO-CPS tool suite under ICA-Internal-EPL or -ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite +ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of ICAPL; or for the case of -redistribution of the INTO-CPS tool suite together with proprietary code it is a dual +redistribution of the INTO-CPS tool suite +together with proprietary code it is a dual license where the INTO-CPS tool suite parts are distributed under ICAPL compatible conditions and the proprietary code is distributed under proprietary license conditions; and @@ -233,9 +264,11 @@ and fitness for a particular purpose; ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; - iii) states that any provisions which differ from ICAPL are offered by that + iii) states that any provisions which differ + from ICAPL are offered by that Contributor alone and not by any other party; and - iv) states from where the source code for the INTO-CPS tool suite is available, and + iv) states from where the source code + for the INTO-CPS tool suite is available, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. @@ -258,9 +291,11 @@ This Agreement is governed by the laws of Denmark. The place of jurisdiction for all disagreements related to this Agreement, is Aarhus, Denmark. The EPL 1.0 license definition has been obtained from: -http://www.eclipse.org/legal/epl-v10.html. It is also reproduced in the INTO-CPS distribution. +http://www.eclipse.org/legal/epl-v10.html. +It is also reproduced in the INTO-CPS distribution. The GPL Version 3 license definition has been obtained from -http://www.gnu.org/copyleft/gpl.html. It is also reproduced in the INTO-CPS distribution. +http://www.gnu.org/copyleft/gpl.html. +It is also reproduced in the INTO-CPS distribution. --- End of Definition of INTO-CPS Association Public License --- diff --git a/client/LICENSE.md b/client/LICENSE.md index be60b871f..c0ad1333c 100644 --- a/client/LICENSE.md +++ b/client/LICENSE.md @@ -1,74 +1,85 @@ +# License + --- Start of Definition of INTO-CPS Association Public License --- /* - * This file is part of the INTO-CPS Association. - * - * Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), - * c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, - * Finlandsgade 22, 8200 Aarhus N, Denmark. - * - * All rights reserved. - * - * THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR - * THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. - * ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES - * RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR - * THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. - * - * The INTO-CPS tool suite software and the INTO-CPS Association - * Public License (ICAPL) are obtained from the INTO-CPS Association, either - * from the above address, from the URLs: http://www.into-cps.org or - * in the INTO-CPS tool suite distribution. - * GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. - * - * This program is distributed WITHOUT ANY WARRANTY; without - * even the implied warranty of MERCHANTABILITY or FITNESS - * FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH - * IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF - * THE INTO-CPS ASSOCIATION PUBLIC LICENSE. - * - * See the full ICAPL conditions for more details. - * + +* This file is part of the INTO-CPS Association. + +* Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), +* c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, +* Finlandsgade 22, 8200 Aarhus N, Denmark. + +* All rights reserved. + +* THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR +* THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. +* ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES +* RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR +* THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. + +* The INTO-CPS tool suite software and the INTO-CPS Association +* Public License (ICAPL) are obtained from the INTO-CPS Association, either +* from the above address, from the URLs: http://www.into-cps.org or +* in the INTO-CPS tool suite distribution. +* GNU version 3 is obtained from: +* http://www.gnu.org/copyleft/gpl.html. + +* This program is distributed WITHOUT ANY WARRANTY; without +* even the implied warranty of MERCHANTABILITY or FITNESS +* FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH +* IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF +* THE INTO-CPS ASSOCIATION PUBLIC LICENSE. + +* See the full ICAPL conditions for more details. + */ --- End of INTO-CPS Association Public License Header --- -The ICAPL is a public license for the INTO-CPS tool suite with three modes/alternatives +The ICAPL is a public license for the INTO-CPS tool +suite with three modes/alternatives (GPL, ICA-Internal-EPL, ICA-External-EPL) for use and redistribution, in source and/or binary/object-code form: -* GPL. Any party (member or non-member of the INTO-CPS Association) may use and +* GPL. Any party (member or non-member of the INTO-CPS Association) may use and redistribute INTO-CPS tool suite under GPL version 3. -* Silver Level members of the INTO-CPS Association may also use and redistribute +* Silver Level members of the INTO-CPS Association may also use and redistribute the INTO-CPS tool suite under ICA-Internal-EPL conditions. -* Gold Level members of the INTO-CPS Association may also use and redistribute +* Gold Level members of the INTO-CPS Association may also use and redistribute The INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions. Definitions of the INTO-CPS Association Public license modes: * GPL = GPL version 3. -* ICA-Internal-EPL = These INTO-CPA Association Public license conditions together with - Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association is only allowed - within the INTO-CPS Association member's own organization (i.e., its own legal entity), - or for a member of the INTO-CPS Association paying a membership fee corresponding to - the size of the organization including all its affiliates, use and redistribution - is allowed within/between its affiliates. - -* ICA-External-EPL = These INTO-CPA Association Public license conditions together with - Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association, or by a Licensed - Third Party Distributor having a redistribution agreement with that member, - to parties external to the INTO-CPS Association member’s own organization (i.e., its own - legal entity) is only allowed in binary/object-code form, except the case of - redistribution to other members the INTO-CPS Association to which source is also - allowed to be distributed. +* ICA-Internal-EPL = These INTO-CPA Association Public + license conditions together with + Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association is only allowed + within the INTO-CPS Association member's own + organization (i.e., its own legal entity), + or for a member of the INTO-CPS Association + paying a membership fee corresponding to + the size of the organization including all its affiliates, use and redistribution + is allowed within/between its affiliates. + +* ICA-External-EPL = These INTO-CPA Association Public + license conditions together with + Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association, or by a Licensed + Third Party Distributor having a redistribution agreement with that member, + to parties external to the INTO-CPS Association + member’s own organization (i.e., its own + legal entity) is only allowed in binary/object-code form, except the case of + redistribution to other members the INTO-CPS Association to which source is also + allowed to be distributed. [This has the consequence that an external party who wishes to use -the INTO-CPS Association in source form together with its own proprietary software in all +the INTO-CPS Association in source form together with +its own proprietary software in all cases must be a member of the INTO-CPS Association]. In all cases of usage and redistribution by recipients, the following @@ -90,7 +101,8 @@ c) A recipient must clearly indicate its chosen usage mode of ICAPL, in accompanying documentation and in a text file ICA-USAGE-MODE.txt, provided with the distribution. -d) Contributor(s) making a Contribution to the INTO-CPS Association thereby also makes a +d) Contributor(s) making a Contribution to the + INTO-CPS Association thereby also makes a Transfer of Contribution Copyright. In return, upon the effective date of the transfer, ICA grants the Contributor(s) a Contribution License of the Contribution. ICA has the right to accept or refuse Contributions. @@ -108,38 +120,46 @@ ICA-Internal-EPL and ICA-External-EPL. INTO-CPS Association Public License version 1.0, i.e., the license defined here (the text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of Definition of INTO-CPS Association Public License ---", or later versions thereof. +"--- End of Definition of INTO-CPS Association +Public License ---", or later versions thereof. "ICAPL Header" means: INTO-CPS Association Public License Header version 1.2, i.e., the -text between "--- Start of Definition of INTO-CPS Association Public License ---" and +text between "--- Start of Definition +of INTO-CPS Association Public License ---" and "--- End of INTO-CPS Association Public License Header ---, or later versions thereof. "Contribution" means: -a) in the case of the initial Contributor, the initial code and documentation +a) in the case of the initial Contributor, + the initial code and documentation distributed under ICAPL, and b) in the case of each subsequent Contributor: i) changes to the INTO-CPS tool suite, and ii) additions to the INTO-CPS tool suite; -where such changes and/or additions to the INTO-CPS tool suite originate from and are -distributed by that particular Contributor. A Contribution 'originates' from -a Contributor if it was added to the INTO-CPS tool suite by such Contributor itself or +where such changes and/or additions +to the INTO-CPS tool suite originate from and are +distributed by that particular Contributor. +A Contribution 'originates' from +a Contributor if it was added to the INTO-CPS +tool suite by such Contributor itself or anyone acting on such Contributor's behalf. For Contributors licensing the INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions, the following conditions also hold: Contributions do not include additions to the distributed Program which: (i) -are separate modules of software distributed in conjunction with the INTO-CPS tool suite +are separate modules of software distributed +in conjunction with the INTO-CPS tool suite under their own license agreement, (ii) are separate modules which are not derivative works of the INTO-CPS tool suite, and (iii) are separate modules of software distributed in conjunction with the INTO-CPS tool suite under their own license agreement where these separate modules are merged with (weaved together with) modules of -The INTO-CPS tool suite to form new modules that are distributed as object code or source +The INTO-CPS tool suite to form new modules +that are distributed as object code or source code under their own license agreement, as allowed under the Additional Condition of internal distribution according to ICA-Internal-EPL and/or Additional Condition for external distribution according to ICA-External-EPL. @@ -147,14 +167,22 @@ Additional Condition for external distribution according to ICA-External-EPL. "Transfer of Contribution Copyright" means that the Contributors of a Contribution transfer the ownership and the copyright of the Contribution to the INTO-CPS Association, the INTO-CPS Association Copyright owner, for -inclusion in the INTO-CPS tool suite. The transfer takes place upon the effective date -when the Contribution is made available on the INTO-CPS Association web site under ICAPL, by +inclusion in the INTO-CPS tool suite. +The transfer takes place upon the effective date +when the Contribution is made available on the +INTO-CPS Association web site under ICAPL, by such Contributors themselves or anyone acting on such Contributors' behalf. -The transfer is free of charge. If the Contributors or the INTO-CPS Association so wish, -an optional Copyright transfer agreement can be signed between the INTO-CPS Association and the Contributors. - -"Contribution License" means a license from the INTO-CPS Association to the Contributors of the Contribution, effective on the date of the Transfer of Contribution Copyright, -where the INTO-CPS Association grants the Contributors a non-exclusive, world-wide, transferable, free of charge, perpetual license, including sublicensing rights, to use, +The transfer is free of charge. If the +Contributors or the INTO-CPS Association so wish, +an optional Copyright transfer agreement can be signed +between the INTO-CPS Association and the Contributors. + +"Contribution License" means a license from the INTO-CPS +Association to the Contributors of the Contribution, effective +on the date of the Transfer of Contribution Copyright, +where the INTO-CPS Association grants the Contributors a +non-exclusive, world-wide, transferable, free of charge, +perpetual license, including sublicensing rights, to use, have used, modify, have modified, reproduce and or have reproduced the contributed material, for business and other purposes, including but not limited to evaluation, development, testing, integration and merging with @@ -166,18 +194,19 @@ the INTO-CPS tool chain. "The Program" means the Contributions distributed in accordance with ICAPL. -"The INTO-CPS tool chain" means the Contributions distributed in accordance with ICAPL. +"The INTO-CPS tool chain" means the Contributions +distributed in accordance with ICAPL. "Recipient" means anyone who receives the INTO-CPS tool chain under ICAPL, including all Contributors. "Licensed Third Party Distributor" means a reseller/distributor having signed -a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS -Association Bylaws, with a Gold Level organizational member which is not an -Affiliate of the reseller/distributor, for distributing a product containing -part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall -only be allowed further redistribution to other resellers if the Gold Level -member is granting such a right to it in the redistribution/resale agreement +a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS +Association Bylaws, with a Gold Level organizational member which is not an +Affiliate of the reseller/distributor, for distributing a product containing +part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall +only be allowed further redistribution to other resellers if the Gold Level +member is granting such a right to it in the redistribution/resale agreement between the Gold Level member and the Licensed Third Party Distributor. "Affiliate" shall mean any legal entity, directly or indirectly, through one @@ -197,7 +226,8 @@ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the -appropriateness of using and distributing the INTO-CPS tool suite and assumes all risks +appropriateness of using and distributing the +INTO-CPS tool suite and assumes all risks associated with its exercise of rights under ICAPL , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability @@ -211,16 +241,17 @@ SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL -SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL +SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. A Contributor licensing the INTO-CPS tool suite under ICA-Internal-EPL or -ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite +ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of ICAPL; or for the case of -redistribution of the INTO-CPS tool suite together with proprietary code it is a dual +redistribution of the INTO-CPS tool suite +together with proprietary code it is a dual license where the INTO-CPS tool suite parts are distributed under ICAPL compatible conditions and the proprietary code is distributed under proprietary license conditions; and @@ -233,9 +264,11 @@ and fitness for a particular purpose; ii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; - iii) states that any provisions which differ from ICAPL are offered by that + iii) states that any provisions which differ + from ICAPL are offered by that Contributor alone and not by any other party; and - iv) states from where the source code for the INTO-CPS tool suite is available, and + iv) states from where the source code + for the INTO-CPS tool suite is available, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. @@ -258,9 +291,11 @@ This Agreement is governed by the laws of Denmark. The place of jurisdiction for all disagreements related to this Agreement, is Aarhus, Denmark. The EPL 1.0 license definition has been obtained from: -http://www.eclipse.org/legal/epl-v10.html. It is also reproduced in the INTO-CPS distribution. +http://www.eclipse.org/legal/epl-v10.html. +It is also reproduced in the INTO-CPS distribution. The GPL Version 3 license definition has been obtained from -http://www.gnu.org/copyleft/gpl.html. It is also reproduced in the INTO-CPS distribution. +http://www.gnu.org/copyleft/gpl.html. +It is also reproduced in the INTO-CPS distribution. --- End of Definition of INTO-CPS Association Public License --- diff --git a/client/README.md b/client/README.md index 9801dd526..979324575 100644 --- a/client/README.md +++ b/client/README.md @@ -1,10 +1,13 @@ # Introduction -Client (frontend) for Digital Twin as a Service (DTaaS) software. This software shall be used for providing a React single page web application for the Digital Twin support platform. +Client (frontend) for Digital Twin as a Service (DTaaS) software. +This software shall be used for providing a React single page web +application for the Digital Twin support platform. ## Setup the Environment and Build -The following steps are required to setup the environment and build the application. +The following steps are required to setup the environment and build +the application. ### Prerequisites @@ -40,31 +43,44 @@ 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 [authentication page](../docs/admin/client/auth.md) +provides details on setting up oauth authentication for +the client application. ## Custom configuration -It is required to have a `env.js` in the root directory of `build` during runtime. This file is used to configure the endpoints of the application. See the [build instructions](../docs/admin/client/CLIENT.md) for an example. +It is required to have a `env.js` in the root directory of +`build` during runtime. This file is used to configure the +endpoints of the application. +See the [build instructions](../docs/admin/client/CLIENT.md) +for an example. ### Multiple configurations -If you want to switch between multiple environments, you can use the `yarn configapp` command to copy a configuration file from `client/config/` to the `build` directory. +If you want to switch between multiple environments, +you can use the `yarn configapp` command to copy a configuration +file from `client/config/` to the `build` directory. 1. Save the file as `client/config/.js`. -2. Run the config command to copy the file to the `public` directory and the `build` directory, if a build is present. +1. Run the config command to copy the file to the `public` directory + and the `build` directory, if a build is present. ```bash yarn configapp ``` -> Which ever env.js file is present in the `public` directory during `yarn build`, will be used in the build. +> Which ever env.js file is present in the `public` directory during +`yarn build`, will be used in the build. -It is therefore reccommend to keep the configurations in the `client/config/` directory and use the `yarn configapp` command to switch between them. +It is therefore reccommend to keep the configurations in the +`client/config/` directory and use the `yarn configapp` command to +switch between them. ## Example configuration for developers -The first step is to collect the URL of gitlab acting as oauth provider. Also collect the client application id. With that information, a configuration file can be made. +The first step is to collect the URL of gitlab acting as oauth provider. +Also collect the client application id. With that information, +a configuration file can be made. A suitable configuration file for developers is: @@ -90,8 +106,9 @@ window.env = { Here the gitlab URL is `https://gitlab.foo.com/` and the client ID is `934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0`. -If a basename is needed for the client application, then the configuration file needs to be updated with the basename. For example, with a basename of `au`, -the `build/env.js` file is given below. +If a basename is needed for the client application, then the configuration +file needs to be updated with the basename. For example, with a basename of +`au`, the `build/env.js` file is given below. ```js window.env = { @@ -113,11 +130,15 @@ window.env = { REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', ``` -Do remember that the oauth application on gitlab needs to have the redirect (callback) URL is correctly registered. +Do remember that the oauth application on gitlab needs to have the redirect +(callback) URL is correctly registered. ## Caveat -The client website relies on the background services to provide most of the functionality. These services would not be running on the developer computer. The complete application setup exists either on the integration server or as an installation instance. During development, there will be +The client website relies on the background services to provide most of the +functionality. These services would not be running on the developer computer. +The complete application setup exists either on the integration server or as an +installation instance. During development, there will be ```txt Unexpected Application Error! diff --git a/client/test/README.md b/client/test/README.md index 560fb80f9..dd62cfd60 100644 --- a/client/test/README.md +++ b/client/test/README.md @@ -1,8 +1,12 @@ # End-to-End (E2E) Tests -The E2E tests require a functional gitlab oauth setup, traefik gateway and a live react client website. The E2E tests do not launch the react client website. So it is important to launch the website using `yarn start`. Keep this server running while performing the E2E tests with `yarn test -e` command. +The E2E tests require a functional gitlab oauth setup, traefik gateway and a +live react client website. The E2E tests do not launch the react client website. +So it is important to launch the website using `yarn start`. Keep this server +running while performing the E2E tests with `yarn test -e` command. -The E2E tests use playwright test runner. You also need to have the software installed. If it is not installed, you can install with the following command. +The E2E tests use playwright test runner. You also need to have the software +installed. If it is not installed, you can install with the following command. ```bash sudo npx playwright install-deps @@ -10,24 +14,34 @@ sudo npx playwright install-deps ## OAuth Setup -You can follow the instructions in [authentication page](../../docs/admin/client/auth.md) to setup oauth for the react client website. Remember to add the `http://localhost:4000` as callback URL in the oauth application. The gitlab will still be running on a remote machine. It is not possible to run both the gitlab and react client website on localhost. +You can follow the instructions in +[authentication page](../../docs/admin/client/auth.md) to setup oauth for the +react client website. Remember to add the `http://localhost:4000` as callback URL +in the oauth application. The gitlab will still be running on a remote machine. +It is not possible to run both the gitlab and react client website on localhost. ## config/test.js file -Before running the E2E tests, you need to update the `config/test.js` file. If you have a live DTaaS client website running, you can copy the `build/env.js` into `config/test.js`. +Before running the E2E tests, you need to update the `config/test.js` file. +If you have a live DTaaS client website running, you can copy the `build/env.js` +into `config/test.js`. -Open `config/test.js` in a text editor and make sure the configuration matches the details of your testing environment. For instance, you need to adjust: +Open `config/test.js` in a text editor and make sure the configuration matches +the details of your testing environment. For instance, you need to adjust: * `REACT_APP_URL` * `REACT_APP_AUTH_AUTHORITY` * `REACT_APP_REDIRECT_URI` * `REACT_APP_LOGOUT_REDIRECT_URI` -to reflect your test setup. More information on about the environment settings is available in [authentication](../../docs/admin/client/auth.md) and [client deployment](../../docs/admin/client/CLIENT.md) pages. +to reflect your test setup. More information on about the environment settings is +available in [authentication](../../docs/admin/client/auth.md) and +[client deployment](../../docs/admin/client/CLIENT.md) pages. -Here's an example of relevant values for variables. This example is suitable for testing on developer computer. +Here's an example of relevant values for variables. This example is suitable for +testing on developer computer. -``` +```js REACT_APP_URL="http://localhost:4000" REACT_APP_AUTH_AUTHORITY="http://gitlab.foo.com" REACT_APP_REDIRECT_URI="http://localhost:4000/Library" @@ -36,7 +50,9 @@ REACT_APP_LOGOUT_REDIRECT_URI="http://localhost:4000" ## env file -You need to create a `test/.env` file where you will store the GitLab user credentials. These credentials will be used by playwright to simulate real user interactions during the E2E tests. +You need to create a `test/.env` file where you will store the GitLab user +credentials. These credentials will be used by playwright to simulate real +user interactions during the E2E tests. A template for `test/.env` is given here: @@ -46,11 +62,14 @@ REACT_APP_TEST_PASSWORD=your_password REACT_APP_URL='https://foo.com' ``` -Replace _your_username_ and _your_password_ with the actual username and password of your GitLab account or the testing account that you intend to use. Finally replace _foo.com_ with the URL of your application, as you did in `env.js`. +Replace _your_username_ and _your_password_ with the actual username and password +of your GitLab account or the testing account that you intend to use. Finally +replace _foo.com_ with the URL of your application, as you did in `env.js`. -Here's an example for test setup on the developer machine and on the integration server: +Here's an example for test setup on the developer machine and on the +integration server: -``` +```env REACT_APP_TEST_USERNAME=TestUsername REACT_APP_TEST_PASSWORD=TestPassword123 REACT_APP_URL='http://localhost:4000' @@ -63,12 +82,16 @@ There are two possible testing setups you can create. 1. Host website on the developer computer and test from developer computer 1. Host website on the integration server and test from the integration server -If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups are essentially the same. -In order to run the tests on the integration server, you need to disable the HTTP authentication (if setup in the first place) on the Traefik server and let the website be accessible without any authenticaiton. +If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups +are essentially the same. +In order to run the tests on the integration server, you need to disable the +HTTP authentication (if setup in the first place) on the Traefik server and +let the website be accessible without any authenticaiton. ### The configuration files for the test on localhost -The `config/test.js` file is given below. The `build/env.js` also holds the same content. +The `config/test.js` file is given below. The `build/env.js` also holds the +same content. ```js window.env = { @@ -91,7 +114,7 @@ window.env = { }; ``` -**test/.env** +## test/.env - localhost ```ini REACT_APP_TEST_USERNAME=TestUsername @@ -99,13 +122,18 @@ REACT_APP_TEST_PASSWORD=TestPassword123 REACT_APP_URL='http://localhost:4000' ``` -Please note that the username and password are the user credentials on `gitlab.foo.com`. +Please note that the username and password are the user +credentials on `gitlab.foo.com`. ## Testing on the integration server -In this test setup, the DTaaS application is running at `https://foo.com` and the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall be run from the developer computer. The codebase commit should be the same on both the developer computer and integration server. +In this test setup, the DTaaS application is running at `https://foo.com` and +the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall +be run from the developer computer. The codebase commit should be the same on +both the developer computer and integration server. -The `config/test.js` file on the developer computer is given below. The `build/env.js` of the integration server also holds the same content. +The `config/test.js` file on the developer computer is given below. The +`build/env.js` of the integration server also holds the same content. ```js window.env = { @@ -128,7 +156,7 @@ window.env = { }; ``` -**test/.env** +## test/.env - Integration server ```ini REACT_APP_TEST_USERNAME=TestUsername @@ -138,13 +166,20 @@ REACT_APP_URL='https://foo.com' Please note that the username and password are the user credentials on `gitlab.foo.com`. -**NOTE:** The tests from developer computer to the integration server only work with null basename. The test fails if a basename (say `au`) is specified. This might be due to a complex interaction of developer computer, traefik gateway and the client website hosted behind traefik. +**NOTE:** The tests from developer computer to the integration server only +work with null basename. The test fails if a basename (say `au`) is specified. +This might be due to a complex interaction of developer computer, traefik +gateway and the client website hosted behind traefik. ## Running the Tests + Once you've properly set up your .env file, you can now run the end-to-end tests. -``` +```bash yarn test -e ``` -This command launches the test runner and executes all end-to-end tests. Make sure you have an active internet connection while running these tests, as they simulate real user interactions with your GitLab account. + +This command launches the test runner and executes all end-to-end tests. +Make sure you have an active internet connection while running these tests, +as they simulate real user interactions with your GitLab account. diff --git a/deploy/README.md b/deploy/README.md index 143843c4b..2af369e2d 100644 --- a/deploy/README.md +++ b/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: _https://foo.com_ +Now you should be able to access the DTaaS application at: _https://foo.com_ diff --git a/deploy/vagrant/make_boxes/dtaas/README.md b/deploy/vagrant/make_boxes/dtaas/README.md index c9826405d..713ad986f 100644 --- a/deploy/vagrant/make_boxes/dtaas/README.md +++ b/deploy/vagrant/make_boxes/dtaas/README.md @@ -1,15 +1,18 @@ +# DTaaS Boxes + This is a box that has the following items: + * docker * nodejs and yarn * jupyter * microk8s * containers - * mltooling/ml-workspace:0.13.2 - * traefik2.5 - * influxdb2.4 - * grafana - * telegraf - * gitlab + * mltooling/ml-workspace:0.13.2 + * traefik2.5 + * influxdb2.4 + * grafana + * telegraf + * gitlab Publish a base virtualbox package to be used by vagrant to publish all other virtualbox packages @@ -28,13 +31,13 @@ vagrant ssh # install the oh-my-zsh sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" -# install plugins: history, autosuggestions, +# install plugins: history, autosuggestions, git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions # inside ~/.zshrc, modify the following line plugins=(git zsh-autosuggestions history cp tmux) -# remove the vagrant default public key - first line of +# remove the vagrant default public key - first line of # /home/vagrant/.ssh/authorized_keys # exit vagrant guest machine and then @@ -42,7 +45,7 @@ plugins=(git zsh-autosuggestions history cp tmux) cp vagrant .vagrant/machines/default/virtualbox/private_key # check -vagrant ssh #should work +vagrant ssh #should work vagrant halt @@ -57,5 +60,6 @@ vagrant box add --name dtaas ./dtaas.vagrant ``` ## TODO + 1. Write a script for automating the above steps 1. Generate the ssh keys from ssl/certificates.bash diff --git a/deploy/vagrant/single-machine/README.md b/deploy/vagrant/single-machine/README.md index 5f85d53d9..d9258cde1 100644 --- a/deploy/vagrant/single-machine/README.md +++ b/deploy/vagrant/single-machine/README.md @@ -4,7 +4,8 @@ This directory contains code for running DTaaS application inside one vagrant VM. The setup requires a machine which can spare 16GB RAM, 8 vCPUs and 50GB Hard Disk space to the vagrant box. -A dummy **foo.com** URL has been used for illustration. Please change this to your unique website URL. +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. @@ -12,13 +13,16 @@ Please follow these steps to make this work in your local environment. You would have created an SSH key pair - _vagrant_ and _vagrant.pub_ for the vagrant box. 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/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. 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 diff --git a/deploy/vagrant/two-machine/README.md b/deploy/vagrant/two-machine/README.md index 10bef807f..2bfb4cb32 100644 --- a/deploy/vagrant/two-machine/README.md +++ b/deploy/vagrant/two-machine/README.md @@ -1,6 +1,8 @@ # DTaaS on Two Vagrant Machines -This directory contains code for running DTaaS application in two vagrant virtual machines (VMs). In this setup, all the user workspaces shall be run on server1 while all the platform services will be run on server2. +This directory contains code for running DTaaS application in two vagrant +virtual machines (VMs). In this setup, all the user workspaces shall be +run on server1 while all the platform services will be run on server2. The setup requires two server VMs with the following hardware configuration: @@ -8,36 +10,57 @@ The setup requires two server VMs with the following hardware configuration: **server2**: 6GB RAM, 3 x64 vCPUs and 50GB Hard Disk space -Under the default configuration, two user workspaces are provisioned on server1. The _workspaces.sh_ contains installation commands for provisioning user workspaces. If you desire to have more users, you need to modify this shell script. +Under the default configuration, two user workspaces are provisioned on +server1. The _workspaces.sh_ contains installation commands for provisioning +user workspaces. If you desire to have more users, you need to modify this +shell script. -The default installation setup also installs InfluxDB, Grafana and RabbitMQ services on server2. If you would like to install more services, you can create shell scripts to install the same on server2. If you have these scripts ready, you can place them in this directory and invoke them from _services.sh_ script. +The default installation setup also installs InfluxDB, Grafana and RabbitMQ +services on server2. If you would like to install more services, you can create +shell scripts to install the same on server2. If you have these scripts ready, +you can place them in this directory and invoke them from _services.sh_ script. ## Create Base Vagrant Box -If you haven't already done it, create [**dtaas** Vagrant box](../make_boxes/dtaas/README.md). Copy _vagrant_ SSH private key here. This shall be useful for logging into the vagrant machines created for two-machine deployment. 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. +If you haven't already done it, +create [**dtaas** Vagrant box](../make_boxes/dtaas/README.md). +Copy _vagrant_ SSH private key here. This shall be useful for logging into the +vagrant machines created for two-machine deployment. 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/two-machine`). +Copy _vagrant_ SSH private key into the current +directory (`deploy/vagrant/two-machine`). ## 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. For that, you need _server name_, _hostname_ and _MAC address_. The hostname is the network URL at which the server can be accessed on the WWW. Please follow these steps to make this work in your local environment. +The first step is to define the network identity of the two VMs. For that, you +need _server name_, _hostname_ and _MAC address_. The hostname is the network +URL at which the server can be accessed on the WWW. Please follow these steps +to make this work in your local environment. -Update the **boxes.json**. There are entries one for each server. The fields to update are: +Update the **boxes.json**. There are entries one for each server. +The fields to update are: 1. `name` - name of server1 (`"name" = "dtaas"`) 1. `hostname` - hostname of server1 (`"name" = "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. 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. `name` - name of server2 (`"name" = "services"`) 1. `hostname` - hostname of server2 (`"name" = "services.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. 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. ## Launch platform default services -RabbitMQ, Grafana and InfluxDB services are provisioned on this server. +RabbitMQ, Grafana and InfluxDB services are provisioned on this server. InfluxDB webUI will be available at: _services.foo.com_. The RabbitMQ service and its management interface shall be available at 5672 and 15672 TCP ports respectively. @@ -58,7 +81,8 @@ wget https://raw.githubusercontent.com/INTO-CPS-Association/DTaaS/feature/distri sudo bash route.sh ``` -After the server is up and running, you can see the following services active within server2. +After the server is up and running, you can see the following services active +within server2. | service | external url | |:---|:---| diff --git a/docs/FAQ.md b/docs/FAQ.md index d57f69ec9..98fee4a0e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -11,189 +11,195 @@ ## General Questions ??? Question "What is DTaaS?" - DTaaS is software platform on which you can create and run digital twins. - Please see the [features](user/features.md) page - to get a sense of the things you can do in DaaS. + +DTaaS is software platform on which you can create and run digital twins. +Please see the [features](user/features.md) page +to get a sense of the things you can do in DaaS. ??? Question "Are there any Key Performance / Capability Indicators for DTaaS?" - | Key Performance Indicator | Value | - |:---|:---| - | Processor | Two AMD EPYC 7443 24-Core Processors | - | Maximum Storage Capacity | 4TB SSD, RAID 0 configuration | - | Storage Type | File System | - | Maximum file size | 10 GB | - | Data transfer speed | 100 Mbps | - | Data Security | Yes | - | Data Privacy | Yes | - | Redundancy | None | - | Availability | It is a matter of human resources. If you have human resources to maintain DTaaS round the clock, upwards 95% is easily possible. | + +| Key Performance Indicator | Value | +|:---|:---| +| Processor | Two AMD EPYC 7443 24-Core Processors | +| Maximum Storage Capacity | 4TB SSD, RAID 0 configuration | +| Storage Type | File System | +| Maximum file size | 10 GB | +| Data transfer speed | 100 Mbps | +| Data Security | Yes | +| Data Privacy | Yes | +| Redundancy | None | +| Availability | It is a matter of human resources. If you have human +resources to maintain DTaaS round the clock, +upwards 95% is easily possible. | ??? Question "Do you provide licensed software like Matlab?" - The licensed software are not available on the software platform. - But users have private workspaces which are based - on Linux-based xfce Desktop environment. - Users can install software in their workspaces. The licensed software - installed by one user is not available to another user. + +The licensed software are not available on the software platform. +But users have private workspaces which are based +on Linux-based xfce Desktop environment. +Users can install software in their workspaces. The licensed software +installed by one user is not available to another user. ## Digital Twin Models ??? Question "Can DTaaS create new DT models?" - 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 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. +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 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. ??? Question "How can DTaaS help to design geometric model? Does it support 3D modeling and simulation?" - Well, DTaaS by itself does not produce any models. DTaaS only provides - a platform and an ecosystem of services to facilitate digital twins to - be run as services. Since each user has a Linux OS at their disposal, - they can also run digital twins that have graphical interface. - In summary, DTaaS is neither a modeling nor simulation tool. If you need - these kinds of tools, you need to bring them onto the platform. - For example, if you need Matlab for your work, you need to bring - he licensed Matlab software. -??? Question "Commercial DT platforms in market provide modelling and simulation alongside integration and UI. DTaas is not able to do any modelling or simulation on its own like other commercial platforms. Is this a correct understanding?" - Yes, you are right +Well, DTaaS by itself does not produce any models. DTaaS only provides +a platform and an ecosystem of services to facilitate digital twins to +be run as services. Since each user has a Linux OS at their disposal, +they can also run digital twins that have graphical interface. +In summary, DTaaS is neither a modeling nor simulation tool. If you need +these kinds of tools, you need to bring them onto the platform. +For example, if you need Matlab for your work, you need to bring +he licensed Matlab software. -??? Question "Can DTaaS support only the information models (or behavioral models) or some other kind of models?" - The DTaaS as such is agnostic to the kind of models you use. DTaaS can - run all kinds of models. This includes behavioral and data models. +??? Question "Commercial DT platforms in market provide modelling and simulation alongside integration and UI. DTaas is not able to do any modelling or simulation on its own like other commercial platforms. Is this a correct understanding?" - As long as you have models and the matching solvers that can run in - Linux OS, you are good to go in DTaaS. +Yes, you are right - In some cases, models and solvers (tools) are bundled together - to form monolithic DTs. The DTaaS does not limit you from running - such DTs as well. +??? Question "Can DTaaS support only the information models (or behavioral models) or some other kind of models?" - DTaaS does not provide dedicated solvers. But if you can install - a solver in your workspace, then you don't need the platform - to provide one. +The DTaaS as such is agnostic to the kind of models you use. DTaaS can +run all kinds of models. This includes behavioral and data models. +As long as you have models and the matching solvers that can run in +Linux OS, you are good to go in DTaaS. +In some cases, models and solvers (tools) are bundled together +to form monolithic DTs. The DTaaS does not limit you from running +such DTs as well. +DTaaS does not provide dedicated solvers. But if you can install +a solver in your workspace, then you don't need the platform +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 ??? Question "How would you measure a physical entity like shape, size, weight, structure, chemical attributes etc. using DTaaS? Any specific technology used in this case?" - The real measurements are done at physical twin which are then - communicated to the digital twin. Any digital twin platform like - DTaaS can only facilitate this communication of these measurements - from physical twin. The DTaaS provides InfluxDB, RabbitMQ and Mosquitto - services for this purpose. These three are probably most widely used - services for digital twin communication. - Having said that, DTaaS allows you to utilize other communication - technologies and services hosted elsewhere on the Internet. +The real measurements are done at physical twin which are then +communicated to the digital twin. Any digital twin platform like +DTaaS can only facilitate this communication of these measurements +from physical twin. The DTaaS provides InfluxDB, RabbitMQ and Mosquitto +services for this purpose. These three are probably most widely used +services for digital twin communication. +Having said that, DTaaS allows you to utilize other communication +technologies and services hosted elsewhere on the Internet. ??? Question "How a real-time data can be differed from static data and what is the procedure to identify dynamic data? Is there any UI or specific tool used here?" - DTaaS can not understand the static or dynamic nature of data. - It can facilitate storing names, units and any other text description - of interesting quantities (weight of batter, voltage output etc). - - It can also store the data being sent by the physical twin. - The distinction between static and dynamic data needs to be made by - the user. - - Only metadata of the data can reveal such more information about - the nature of data. A tool can probably help in very specific cases, - but you need metadata. If there is a human being making this distinction, - then the need for metadata goes down but does not completely go away. - - In some of the DT platforms supported by manufacturers, there is a tight - integration between data and model. In this case, the tool itself is - taking care of the metadata. The DTaaS is a generic platform which can - support execution of digital twins. If a tool can be executed on - a Linux desktop / commandline, the tool can be supported within DTaaS. - The tool (ex. Matlab) itself can take care of the metadata requirements. + +DTaaS can not understand the static or dynamic nature of data. +It can facilitate storing names, units and any other text description +of interesting quantities (weight of batter, voltage output etc). +It can also store the data being sent by the physical twin. +The distinction between static and dynamic data needs to be made by +the user. +Only metadata of the data can reveal such more information about +the nature of data. A tool can probably help in very specific cases, +but you need metadata. If there is a human being making this distinction, +then the need for metadata goes down but does not completely go away. +In some of the DT platforms supported by manufacturers, there is a tight +integration between data and model. In this case, the tool itself is +taking care of the metadata. The DTaaS is a generic platform which can +support execution of digital twins. If a tool can be executed on +a Linux desktop / commandline, the tool can be supported within DTaaS. +The tool (ex. Matlab) itself can take care of the metadata requirements. ??? Question "How can DTaaS control the physical entity? Which technologies it uses for controlling the physical world?" - At a very abstract level, there is a communication from physical entity - to digital entity and back to physical entity. How this communication - should happen is decided by the person designing the digital entity. - The DTaaS can provide communication services that can help you do this - communication with relative ease. - You can use InfluxDB, RabbitMQ and Mosquitto services hosted on DTaaS for - two communication between digital and physical entities. +At a very abstract level, there is a communication from physical entity +to digital entity and back to physical entity. How this communication +should happen is decided by the person designing the digital entity. +The DTaaS can provide communication services that can help you do this +communication with relative ease. +You can use InfluxDB, RabbitMQ and Mosquitto services hosted on DTaaS for +two communication between digital and physical entities. ## Data Management ??? Question "Does DTaaS support data collection from different sources like hardware, software and network? Is there any user interface or any tracking instruments used for data collection?" - The DTaaS provids InfluxDB, RabbitMQ, MQTT services. Both the physical twin - and digital twin can utilize these protocols for communication. - - The IoT (time-series) data can be collected using InfluxDB and MQTT - broker services. There is a user interface for InfluxDB which can be - used to analyze the data collected. - Users can also manually upload their data files into DTaaS. +The DTaaS provids InfluxDB, RabbitMQ, MQTT services. Both the physical twin +and digital twin can utilize these protocols for communication. +The IoT (time-series) data can be collected using InfluxDB and MQTT +broker services. There is a user interface for InfluxDB which can be +used to analyze the data collected. +Users can also manually upload their data files into DTaaS. ??? Question "Which transmission protocol does DTaaS allow?" - InfluxDB, RabbitMQ, MQTT and anything else that can be used from - Cloud service providers. + +InfluxDB, RabbitMQ, MQTT and anything else that can be used from +Cloud service providers. ??? Question "Does DTaaS support multisource information and combined multi sensor input data? Can it provide analysis and decision-supporting inferences?" - You can store information from multiple sources. The existing InfluxDB - services hosted on DTaaS already has a dedicated Influx / Flux query - language for doing sensor fusion, analysis and inferences. + +You can store information from multiple sources. The existing InfluxDB +services hosted on DTaaS already has a dedicated Influx / Flux query +language for doing sensor fusion, analysis and inferences. ??? Question "Which kinds of visualization technologies DTaaS can support (e.g. graphical, geometry, image, VR/AR representation)?" - Graphical, geometric and images. If you need specific licensed software - for the visualization, you will have to bring the license for it. - DTaaS does not support AR/VR. + +Graphical, geometric and images. If you need specific licensed software +for the visualization, you will have to bring the license for it. +DTaaS does not support AR/VR. ??? Question "Can DTaaS collect data directly from sensors?" - Yes + +Yes ??? Question "Is DTaaS able to transmit data to cloud in real time?" - Yes + +Yes ## Platform Native Services on DTaaS Platform ??? Question "Is DTaaS able to detect the anomalies about-to-fail components and prescribe solutions?" - This is the job of a digital twin. If you have a ready to use digital twin - that does the job, DTaaS allows others to use your solution. + +This is the job of a digital twin. If you have a ready to use digital twin +that does the job, DTaaS allows others to use your solution. ## Comparison with other DT Platforms ??? Question "All the DT platforms seem to provide different features. Is there a comparison chart?" - Here is a qualitative comparison of different DT integration platforms: - - Legend: high performance (**H**), mid performance (**M**) - and low performance (**L**) - - | DT Platforms | License | DT Development Process | Connectivity | Security | Processing power, performance and Scalability | Data Storage | Visualization | Modeling and Simulation | - |:---|:---|:---|:---|:---|:---|:---|:---|:---| - | Microsoft Azure DT | Commercial Cloud | H | H | H | M | H | H | H | - | AWS IOT Greengrass | Open source commercial | H | H | H | M | H | H | H | - | Eclipse Ditto | Open source | M | H | M | H | H | L | L | - | Asset Administration Shell | Open source | H | H | L | H | M | L | M | - | PTC Thingworx | Commercial | H | H | H | H | H | M | M | - | GE Predix | Commercial | M | H | H | M | L | M | L | - | AU's DTaaS | Open source | H | H | L | L | M | M | M | - Adopted by Tanusree Roy from Table 4 and 5 of the following paper. - - Ref: Naseri, F., Gil, S., Barbu, C., Cetkin, E., Yarimca, G., Jensen, A. C., - ... & Gomes, C. (2023). Digital twin of electric vehicle battery systems: - Comprehensive review of the use cases, requirements, and platforms. - Renewable and Sustainable Energy Reviews, 179, 113280. +Here is a qualitative comparison of different DT integration platforms: +Legend: high performance (**H**), mid performance (**M**) +and low performance (**L**) +| DT Platforms | License | DT Development Process | Connectivity | Security | Processing power, performance and Scalability | Data Storage | Visualization | Modeling and Simulation | +|:---|:---|:---|:---|:---|:---|:---|:---|:---| +| Microsoft Azure DT | Commercial Cloud | H | H | H | M | H | H | H | +| AWS IOT Greengrass | Open source commercial | H | H | H | M | H | H | H | +| Eclipse Ditto | Open source | M | H | M | H | H | L | L | +| Asset Administration Shell | Open source | H | H | L | H | M | L | M | +| PTC Thingworx | Commercial | H | H | H | H | H | M | M | +| GE Predix | Commercial | M | H | H | M | L | M | L | +| AU's DTaaS | Open source | H | H | L | L | M | M | M | +Adopted by Tanusree Roy from Table 4 and 5 of the following paper. +Ref: Naseri, F., Gil, S., Barbu, C., Cetkin, E., Yarimca, G., Jensen, A. C., +... & Gomes, C. (2023). Digital twin of electric vehicle battery systems: +Comprehensive review of the use cases, requirements, and platforms. +Renewable and Sustainable Energy Reviews, 179, 113280. ??? Question "All the comparisons between DT platforms seems so confusing. Why?" - The fundamental confusion comes from the fact that different DT platforms - (Azure DT, GE Predix) provide different kind of DT capabilities. You can - run all kinds of models natively in GE Predix. In fact you can run models - even next to (on) PTs using GE Predix. But you cannot natively do that in - Azure DT service. You have to do the leg work of integrating with other - Azure services or third-party services to get the kind of capabilities - that GE Predix natively provides in one interface. - - The takeaway is that we pick horses for the courses. + +The fundamental confusion comes from the fact that different DT platforms +(Azure DT, GE Predix) provide different kind of DT capabilities. You can +run all kinds of models natively in GE Predix. In fact you can run models +even next to (on) PTs using GE Predix. But you cannot natively do that in +Azure DT service. You have to do the leg work of integrating with other +Azure services or third-party services to get the kind of capabilities +that GE Predix natively provides in one interface. +The takeaway is that we pick horses for the courses. diff --git a/docs/LICENSE.md b/docs/LICENSE.md index be60b871f..00cda86b7 100644 --- a/docs/LICENSE.md +++ b/docs/LICENSE.md @@ -1,75 +1,87 @@ +# License + --- Start of Definition of INTO-CPS Association Public License --- /* - * This file is part of the INTO-CPS Association. - * - * Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), - * c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, - * Finlandsgade 22, 8200 Aarhus N, Denmark. - * - * All rights reserved. - * - * THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR - * THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. - * ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES - * RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR - * THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. - * - * The INTO-CPS tool suite software and the INTO-CPS Association - * Public License (ICAPL) are obtained from the INTO-CPS Association, either - * from the above address, from the URLs: http://www.into-cps.org or - * in the INTO-CPS tool suite distribution. - * GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. - * - * This program is distributed WITHOUT ANY WARRANTY; without - * even the implied warranty of MERCHANTABILITY or FITNESS - * FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH - * IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF - * THE INTO-CPS ASSOCIATION PUBLIC LICENSE. - * - * See the full ICAPL conditions for more details. - * + +* This file is part of the INTO-CPS Association. + +* Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), +* c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, +* Finlandsgade 22, 8200 Aarhus N, Denmark. + +* All rights reserved. + +* THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR +* THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. +* ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES +* RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR +* THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. + +* The INTO-CPS tool suite software and the INTO-CPS Association +* Public License (ICAPL) are obtained from the INTO-CPS Association, either +* from the above address, from the URLs: http://www.into-cps.org or +* in the INTO-CPS tool suite distribution. +* GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. + +* This program is distributed WITHOUT ANY WARRANTY; without +* even the implied warranty of MERCHANTABILITY or FITNESS +* FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH +* IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF +* THE INTO-CPS ASSOCIATION PUBLIC LICENSE. + +* See the full ICAPL conditions for more details. + */ --- End of INTO-CPS Association Public License Header --- -The ICAPL is a public license for the INTO-CPS tool suite with three modes/alternatives +The ICAPL is a public license for the INTO-CPS tool suite with three +modes/alternatives (GPL, ICA-Internal-EPL, ICA-External-EPL) for use and redistribution, in source and/or binary/object-code form: -* GPL. Any party (member or non-member of the INTO-CPS Association) may use and - redistribute INTO-CPS tool suite under GPL version 3. +* GPL. Any party (member or non-member of the INTO-CPS Association) may use + and redistribute INTO-CPS tool suite under GPL version 3. -* Silver Level members of the INTO-CPS Association may also use and redistribute - the INTO-CPS tool suite under ICA-Internal-EPL conditions. +* Silver Level members of the INTO-CPS Association may also use and + redistribute the INTO-CPS tool suite under ICA-Internal-EPL conditions. -* Gold Level members of the INTO-CPS Association may also use and redistribute +* Gold Level members of the INTO-CPS Association may also use and redistribute The INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions. Definitions of the INTO-CPS Association Public license modes: * GPL = GPL version 3. -* ICA-Internal-EPL = These INTO-CPA Association Public license conditions together with - Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association is only allowed - within the INTO-CPS Association member's own organization (i.e., its own legal entity), - or for a member of the INTO-CPS Association paying a membership fee corresponding to - the size of the organization including all its affiliates, use and redistribution - is allowed within/between its affiliates. - -* ICA-External-EPL = These INTO-CPA Association Public license conditions together with - Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association, or by a Licensed - Third Party Distributor having a redistribution agreement with that member, - to parties external to the INTO-CPS Association member’s own organization (i.e., its own - legal entity) is only allowed in binary/object-code form, except the case of - redistribution to other members the INTO-CPS Association to which source is also - allowed to be distributed. +* ICA-Internal-EPL = These INTO-CPA Association Public license conditions + together with + Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association is only + allowed within the INTO-CPS Association member's own organization + (i.e., its own legal entity), + or for a member of the INTO-CPS Association paying a membership fee + corresponding to + the size of the organization including all its affiliates, + use and redistribution + is allowed within/between its affiliates. + +* ICA-External-EPL = These INTO-CPA Association Public license conditions + together with + Externally restricted EPL, i.e., EPL version 1.0 with the Additional + Condition + that use and redistribution by a member of the INTO-CPS Association, or + by a Licensed + Third Party Distributor having a redistribution agreement with that member, + to parties external to the INTO-CPS Association member’s own organization + (i.e., its own + legal entity) is only allowed in binary/object-code form, except the case of + redistribution to other members the INTO-CPS Association to which source is + also allowed to be distributed. [This has the consequence that an external party who wishes to use -the INTO-CPS Association in source form together with its own proprietary software in all -cases must be a member of the INTO-CPS Association]. +the INTO-CPS Association in source form together with its own proprietary +software in all cases must be a member of the INTO-CPS Association]. In all cases of usage and redistribution by recipients, the following conditions also apply: @@ -90,7 +102,8 @@ c) A recipient must clearly indicate its chosen usage mode of ICAPL, in accompanying documentation and in a text file ICA-USAGE-MODE.txt, provided with the distribution. -d) Contributor(s) making a Contribution to the INTO-CPS Association thereby also makes a +d) Contributor(s) making a Contribution to the INTO-CPS Association thereby + also makes a Transfer of Contribution Copyright. In return, upon the effective date of the transfer, ICA grants the Contributor(s) a Contribution License of the Contribution. ICA has the right to accept or refuse Contributions. @@ -108,13 +121,16 @@ ICA-Internal-EPL and ICA-External-EPL. INTO-CPS Association Public License version 1.0, i.e., the license defined here (the text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of Definition of INTO-CPS Association Public License ---", or later versions thereof. +"--- End of Definition of INTO-CPS Association Public License ---", or later +versions thereof. "ICAPL Header" means: INTO-CPS Association Public License Header version 1.2, i.e., the -text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of INTO-CPS Association Public License Header ---, or later versions thereof. +text between "--- Start of Definition of INTO-CPS Association Public License +---" and +"--- End of INTO-CPS Association Public License Header ---, or later versions +thereof. "Contribution" means: @@ -125,36 +141,48 @@ b) in the case of each subsequent Contributor: i) changes to the INTO-CPS tool suite, and ii) additions to the INTO-CPS tool suite; -where such changes and/or additions to the INTO-CPS tool suite originate from and are +where such changes and/or additions to the INTO-CPS tool suite originate from +and are distributed by that particular Contributor. A Contribution 'originates' from -a Contributor if it was added to the INTO-CPS tool suite by such Contributor itself or +a Contributor if it was added to the INTO-CPS tool suite by such Contributor +itself or anyone acting on such Contributor's behalf. For Contributors licensing the INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions, the following conditions also hold: Contributions do not include additions to the distributed Program which: (i) -are separate modules of software distributed in conjunction with the INTO-CPS tool suite +are separate modules of software distributed in conjunction with the INTO-CPS +tool suite under their own license agreement, (ii) are separate modules which are not -derivative works of the INTO-CPS tool suite, and (iii) are separate modules of software -distributed in conjunction with the INTO-CPS tool suite under their own license agreement +derivative works of the INTO-CPS tool suite, and (iii) are separate modules of +software distributed in conjunction with the INTO-CPS tool suite under their +own license agreement where these separate modules are merged with (weaved together with) modules of -The INTO-CPS tool suite to form new modules that are distributed as object code or source -code under their own license agreement, as allowed under the Additional +The INTO-CPS tool suite to form new modules that are distributed as object code +or source code under their own license agreement, as allowed under the Additional Condition of internal distribution according to ICA-Internal-EPL and/or Additional Condition for external distribution according to ICA-External-EPL. "Transfer of Contribution Copyright" means that the Contributors of a Contribution transfer the ownership and the copyright of the Contribution to the INTO-CPS Association, the INTO-CPS Association Copyright owner, for -inclusion in the INTO-CPS tool suite. The transfer takes place upon the effective date -when the Contribution is made available on the INTO-CPS Association web site under ICAPL, by +inclusion in the INTO-CPS tool suite. The transfer takes place upon the +effective date +when the Contribution is made available on the INTO-CPS Association web +site under ICAPL, by such Contributors themselves or anyone acting on such Contributors' behalf. -The transfer is free of charge. If the Contributors or the INTO-CPS Association so wish, -an optional Copyright transfer agreement can be signed between the INTO-CPS Association and the Contributors. - -"Contribution License" means a license from the INTO-CPS Association to the Contributors of the Contribution, effective on the date of the Transfer of Contribution Copyright, -where the INTO-CPS Association grants the Contributors a non-exclusive, world-wide, transferable, free of charge, perpetual license, including sublicensing rights, to use, +The transfer is free of charge. If the Contributors or the +INTO-CPS Association so wish, +an optional Copyright transfer agreement can be signed between the INTO-CPS +Association and the Contributors. + +"Contribution License" means a license from the INTO-CPS Association to the +Contributors of the Contribution, effective on the date of the Transfer of +Contribution Copyright, +where the INTO-CPS Association grants the Contributors a non-exclusive, +world-wide, transferable, free of charge, perpetual license, including +sublicensing rights, to use, have used, modify, have modified, reproduce and or have reproduced the contributed material, for business and other purposes, including but not limited to evaluation, development, testing, integration and merging with @@ -166,18 +194,19 @@ the INTO-CPS tool chain. "The Program" means the Contributions distributed in accordance with ICAPL. -"The INTO-CPS tool chain" means the Contributions distributed in accordance with ICAPL. +"The INTO-CPS tool chain" means the Contributions distributed in accordance +with ICAPL. "Recipient" means anyone who receives the INTO-CPS tool chain under ICAPL, including all Contributors. "Licensed Third Party Distributor" means a reseller/distributor having signed -a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS -Association Bylaws, with a Gold Level organizational member which is not an -Affiliate of the reseller/distributor, for distributing a product containing -part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall -only be allowed further redistribution to other resellers if the Gold Level -member is granting such a right to it in the redistribution/resale agreement +a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS +Association Bylaws, with a Gold Level organizational member which is not an +Affiliate of the reseller/distributor, for distributing a product containing +part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall +only be allowed further redistribution to other resellers if the Gold Level +member is granting such a right to it in the redistribution/resale agreement between the Gold Level member and the Licensed Third Party Distributor. "Affiliate" shall mean any legal entity, directly or indirectly, through one @@ -192,12 +221,14 @@ voting securities, by contract or otherwise. NO WARRANTY EXCEPT AS EXPRESSLY SET FORTH IN THE BY RECIPIENT SELECTED SUBSIDIARY -LICENSE CONDITIONS OF ICAPL, THE INTO-CPS ASSOCIATION IS PROVIDED ON AN "AS IS" +LICENSE CONDITIONS OF ICAPL, THE INTO-CPS ASSOCIATION IS PROVIDED ON AN +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the -appropriateness of using and distributing the INTO-CPS tool suite and assumes all risks +appropriateness of using and distributing the INTO-CPS tool suite and assumes +all risks associated with its exercise of rights under ICAPL , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability @@ -211,16 +242,17 @@ SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL -SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL +SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. A Contributor licensing the INTO-CPS tool suite under ICA-Internal-EPL or -ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite +ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of ICAPL; or for the case of -redistribution of the INTO-CPS tool suite together with proprietary code it is a dual +redistribution of the INTO-CPS tool suite together with proprietary code it +is a dual license where the INTO-CPS tool suite parts are distributed under ICAPL compatible conditions and the proprietary code is distributed under proprietary license conditions; and @@ -235,7 +267,8 @@ damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) states that any provisions which differ from ICAPL are offered by that Contributor alone and not by any other party; and - iv) states from where the source code for the INTO-CPS tool suite is available, and + iv) states from where the source code for the INTO-CPS tool suite is + available, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange. @@ -258,9 +291,13 @@ This Agreement is governed by the laws of Denmark. The place of jurisdiction for all disagreements related to this Agreement, is Aarhus, Denmark. The EPL 1.0 license definition has been obtained from: -http://www.eclipse.org/legal/epl-v10.html. It is also reproduced in the INTO-CPS distribution. +http://www.eclipse.org/legal/epl-v10.html. +It is also reproduced in the INTO-CPS +distribution. The GPL Version 3 license definition has been obtained from -http://www.gnu.org/copyleft/gpl.html. It is also reproduced in the INTO-CPS distribution. +http://www.gnu.org/copyleft/gpl.html. +It is also reproduced in the INTO-CPS +distribution. --- End of Definition of INTO-CPS Association Public License --- diff --git a/docs/PUBLISH.md b/docs/PUBLISH.md index bd36dc85d..d77ae3664 100644 --- a/docs/PUBLISH.md +++ b/docs/PUBLISH.md @@ -1,4 +1,3 @@ - # Project Documentation This file contains instructions for creation, compilation and publication of @@ -8,7 +7,8 @@ The documentation system is based on [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/). The documentation is generated based on the configuration files: -* **mkdocs.yml**: used for generating online documentation which is hosted on the web +* **mkdocs.yml**: used for generating online + documentation which is hosted on the web * **mkdocs-github.yml**: used for generating documentation in github actions Install Mkdocs using the following command. diff --git a/docs/admin/client/CLIENT.md b/docs/admin/client/CLIENT.md index 79afce31b..7a611e143 100644 --- a/docs/admin/client/CLIENT.md +++ b/docs/admin/client/CLIENT.md @@ -2,85 +2,90 @@ To host DTaaS client website on your server, follow these steps: -- Download the **DTaaS-client.zip** from the [releases page](https://github.com/INTO-CPS-Association/DTaaS/releases). +- Download the **DTaaS-client.zip** from the + [releases page](https://github.com/INTO-CPS-Association/DTaaS/releases). - Inside the `DTaaS-client` directory, there is `site` directory. The `site` directory contains all the optimized static files that are ready for deployment. - Setup the oauth application on gitlab instance. See the instructions in [authentication page](auth.md) for completing this task. -- Locate the file `site/env.js` and replace the example values to match your infrastructure. - The constructed links will be "`REACT_APP_URL`/`REACT_APP_URL_BASENAME`/`{username}`/`{Endpoint}`". +- Locate the file `site/env.js` and replace the example values to + match your infrastructure. + The constructed links will be + "`REACT_APP_URL`/`REACT_APP_URL_BASENAME`/`{username}`/`{Endpoint}`". See the definitions below: - ```js - window.env = { - REACT_APP_ENVIRONMENT: "prod | dev", - REACT_APP_URL: "URL for the gateway", - REACT_APP_URL_BASENAME: "Base URL for the client website"(optional), - REACT_APP_URL_DTLINK: "Endpoint for the Digital Twin", - REACT_APP_URL_LIBLINK: "Endpoint for the Library Assets", - REACT_APP_WORKBENCHLINK_TERMINAL: "Endpoint for the terminal link", - REACT_APP_WORKBENCHLINK_VNCDESKTOP: "Endpoint for the VNC Desktop link", - REACT_APP_WORKBENCHLINK_VSCODE: "Endpoint for the VS Code link", - REACT_APP_WORKBENCHLINK_JUPYTERLAB: "Endpoint for the Jupyter Lab link", - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: - "Endpoint for the Jupyter Notebook link", - - REACT_APP_CLIENT_ID: 'AppID genereated by the gitlab OAuth provider', - REACT_APP_AUTH_AUTHORITY: 'URL of the private gitlab instance', - REACT_APP_REDIRECT_URI: 'URL of the homepage for the logged in users of the website', - REACT_APP_LOGOUT_REDIRECT_URI: 'URL of the homepage for the anonymous users of the website', - REACT_APP_GITLAB_SCOPES: 'OAuth scopes. These should match with the scopes set in gitlab OAuth provider', - }; - - // Example values with no base URL. Trailing and ending slashes are optional. - window.env = { - REACT_APP_ENVIRONMENT: 'prod', - REACT_APP_URL: 'https://foo.com/', - REACT_APP_URL_BASENAME: '', - REACT_APP_URL_DTLINK: '/lab', - REACT_APP_URL_LIBLINK: '', - REACT_APP_WORKBENCHLINK_TERMINAL: '/terminals/main', - REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', - REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', - REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', - - REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', - REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/', - REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', - }; - - // Example values with "bar" as basename URL. Trailing and ending slashes are optional. - window.env = { - REACT_APP_ENVIRONMENT: "dev", - REACT_APP_URL: 'https://foo.com/', - REACT_APP_URL_BASENAME: 'bar', - REACT_APP_URL_DTLINK: '/lab', - REACT_APP_URL_LIBLINK: '', - REACT_APP_WORKBENCHLINK_TERMINAL: '/terminals/main', - REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', - REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', - REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', - - REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', - REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/bar/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/bar', - REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', - }; - ``` - -- Copy the entire contents of the build folder to the root directory of your server where you want to deploy the app. You can use FTP, SFTP, or any other file transfer protocol to transfer the files. - -- Make sure your server is configured to serve static files. This can vary depending on the server technology you are using, but typically you will need to configure your server to serve files from a specific directory. - -- Once the files are on your server, you should be able to access your app by visiting your server's IP address or domain name in a web browser. - + ```js + window.env = { + REACT_APP_ENVIRONMENT: "prod | dev", + REACT_APP_URL: "URL for the gateway", + REACT_APP_URL_BASENAME: "Base URL for the client website"(optional), + REACT_APP_URL_DTLINK: "Endpoint for the Digital Twin", + REACT_APP_URL_LIBLINK: "Endpoint for the Library Assets", + REACT_APP_WORKBENCHLINK_TERMINAL: "Endpoint for the terminal link", + REACT_APP_WORKBENCHLINK_VNCDESKTOP: "Endpoint for the VNC Desktop link", + REACT_APP_WORKBENCHLINK_VSCODE: "Endpoint for the VS Code link", + REACT_APP_WORKBENCHLINK_JUPYTERLAB: "Endpoint for the Jupyter Lab link", + REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: + "Endpoint for the Jupyter Notebook link", + REACT_APP_CLIENT_ID: 'AppID genereated by the gitlab OAuth provider', + REACT_APP_AUTH_AUTHORITY: 'URL of the private gitlab instance', + REACT_APP_REDIRECT_URI: 'URL of the homepage for the logged in users of the website', + REACT_APP_LOGOUT_REDIRECT_URI: 'URL of the homepage for the anonymous users of the website', + REACT_APP_GITLAB_SCOPES: 'OAuth scopes. These should match with the scopes set in gitlab OAuth provider', + }; + + // Example values with no base URL. Trailing and ending slashes are optional. + window.env = { + REACT_APP_ENVIRONMENT: 'prod', + REACT_APP_URL: 'https://foo.com/', + REACT_APP_URL_BASENAME: '', + REACT_APP_URL_DTLINK: '/lab', + REACT_APP_URL_LIBLINK: '', + REACT_APP_WORKBENCHLINK_TERMINAL: '/terminals/main', + REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', + REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', + REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', + REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', + REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', + REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', + REACT_APP_REDIRECT_URI: 'https://foo.com/Library', + REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/', + REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', + }; + + // Example values with "bar" as basename URL. + //Trailing and ending slashes are optional. + window.env = { + REACT_APP_ENVIRONMENT: "dev", + REACT_APP_URL: 'https://foo.com/', + REACT_APP_URL_BASENAME: 'bar', + REACT_APP_URL_DTLINK: '/lab', + REACT_APP_URL_LIBLINK: '', + REACT_APP_WORKBENCHLINK_TERMINAL: '/terminals/main', + REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', + REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', + REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', + REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', + REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', + REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', + REACT_APP_REDIRECT_URI: 'https://foo.com/bar/Library', + REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/bar', + REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', + }; + ``` + +- Copy the entire contents of the build folder to the root directory of your + server where you want to deploy the app. You can use FTP, SFTP, or any + other file transfer protocol to transfer the files. + +- Make sure your server is configured to serve static files. This can vary + depending on the server technology you are using, but typically you will + need to configure your server to serve files from a specific directory. + +- Once the files are on your server, you should be able to access your app + by visiting your server's IP address or domain name in a web browser. :fontawesome-solid-circle-info: The website depends on **Traefik gateway** and **ML Workspace** @@ -101,7 +106,8 @@ https:foo.com//tools/vscode/ ``` The `username` is the user workspace created using ML Workspace docker container. -Please follow the instructions in [README](https://github.com/ml-tooling/ml-workspace/blob/main/README.md). +Please follow the instructions in +[README](https://github.com/ml-tooling/ml-workspace/blob/main/README.md). You can create as many user workspaces as you want. If you have two users - alice and bob - on your system, then the following the commands in will instantiate the required user workspaces. @@ -121,8 +127,6 @@ docker run -d \ --restart always \ mltooling/ml-workspace:0.13.2 - - docker run -d \ -p 8091:8080 \ --name "ml-workspace-bob" \ @@ -137,4 +141,5 @@ docker run -d \ Given that multiple services are running at different routes, a reverse proxy is needed to map the background services to external routes. -You can use Apache, NGINX, Traefik or any other software to work as reverse proxy. \ No newline at end of file +You can use Apache, NGINX, Traefik or any other software to work +as reverse proxy. \ No newline at end of file diff --git a/docs/admin/client/auth.md b/docs/admin/client/auth.md index 2dcfc94f3..995575a5c 100644 --- a/docs/admin/client/auth.md +++ b/docs/admin/client/auth.md @@ -1,11 +1,25 @@ - # OAuth Authentication for React 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. The simplest way to make this work is to 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. +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. The simplest way to make this work is to 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. @@ -16,7 +30,8 @@ Callback URL: https://foo.com/Library Logout URL: https://foo.com ``` -If you choose to host your DTaaS application with a basename (say bar), then the URLs change to: +If you choose to host your DTaaS application with a basename (say bar), then the +URLs change to: ```txt DTaaS application URL: https://foo.com/bar @@ -25,11 +40,16 @@ Callback URL: https://foo.com/bar/Library Logout URL: https://foo.com/bar ``` -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. +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. -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 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`. -The mapping between the oauth URLs and the environment variables in `env.js` is shown below. +The mapping between the oauth URLs and the environment variables in `env.js` +is shown below. | URL | Variable name in env.js | |:---|:---| @@ -39,11 +59,17 @@ The mapping between the oauth URLs and the environment variables in `env.js` is | Logout URL | REACT_APP_LOGOUT_REDIRECT_URI | || -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. +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. ## Development Environment -There needs to be a valid callback and logout URLs for development and testing purposes. You can use the same oauth application id for both development, testing and deployment scenarios. Only the callback and logout URLs change. It is possible to register multiple callback URLs in one oauth application. In order to use oauth for development and testing on developer computer (localhost), you need to add the following to oauth callback URL. +There needs to be a valid callback and logout URLs for development and testing +purposes. You can use the same oauth application id for both development, testing +and deployment scenarios. Only the callback and logout URLs change. It is possible +to register multiple callback URLs in one oauth application. In order to use oauth +for development and testing on developer computer (localhost), you need to add the +following to oauth callback URL. ```txt DTaaS application URL: http://localhost:4000 @@ -55,7 +81,9 @@ The port 4000 is the default port for running the client website. ## Multiple DTaaS applications -The DTaaS is a regular web application. It is possible to host multiple DTaaS applications on the same server. The only requirement is to have a distinct URLs. You can have three DTaaS applications running at the following URLs. +The DTaaS is a regular web application. It is possible to host multiple DTaaS +applications on the same server. The only requirement is to have a distinct URLs. +You can have three DTaaS applications running at the following URLs. ```txt https://foo.com/au @@ -72,4 +100,7 @@ All of these instances can use the same gitlab instance for authentication. | https://foo.com/bar | https://foo.gitlab.com | https://foo.com/au/Library | https://foo.com/au | autogenerated by gitlab | || -If you are hosting multiple DTaaS instances on the same server, do not a 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. \ No newline at end of file +If you are hosting multiple DTaaS instances on the same server, +do not a 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. \ No newline at end of file diff --git a/docs/admin/servers/lib/LIB-MS.md b/docs/admin/servers/lib/LIB-MS.md index fd44c44b3..9e86daa0b 100644 --- a/docs/admin/servers/lib/LIB-MS.md +++ b/docs/admin/servers/lib/LIB-MS.md @@ -7,7 +7,9 @@ It has three features: * transfer a file to user. * 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 with various resources. +The library microservice is designed to manage and serve files, +functions, and models to users, allowing them to access and interact +with various resources. This document provides instructions for running a stand alone library microservice. @@ -17,7 +19,9 @@ The users expect the following file system structure for their reusable assets. ![File System Layout](file-system-layout.png) -There is a skeleton file structure in [DTaaS codebase](https://github.com/INTO-CPS-Association/DTaaS/tree/feature/distributed-demo/files). You can copy and create file system for your users. +There is a skeleton file structure in +[DTaaS codebase](https://github.com/INTO-CPS-Association/DTaaS/tree/feature/distributed-demo/files). +You can copy and create file system for your users. ## Gitlab setup (optional) @@ -38,7 +42,8 @@ to get a sample file system structure for the lib microservice. To set up the lib microservice, follow these steps: -Download the **lib-microservice.zip** from the [releases page](https://github.com/INTO-CPS-Association/DTaaS/releases). +Download the **lib-microservice.zip** from the +[releases page](https://github.com/INTO-CPS-Association/DTaaS/releases). ## Configuration setup @@ -77,8 +82,10 @@ Replace the default values the appropriate values for your setup. **NOTE**: -1. When \__MODE=local_, only _LOCAL_PATH_ is used. Other environment variables are unused. -1. When _MODE=gitlab_, _GITLAB_URL, TOKEN_, and _GITLAB_GROUP_ are used; _LOCAL_PATH_ is unused. +1. When \__MODE=local_, only _LOCAL_PATH_ is used. + Other environment variables are unused. +1. When _MODE=gitlab_, _GITLAB_URL, TOKEN_, + and _GITLAB_GROUP_ are used; _LOCAL_PATH_ is unused. ### Start Microservice @@ -109,7 +116,7 @@ The lib microservice supports two GraphQL queries. ### Directory Listing -#### Query +#### Query: List of Files To retrieve a list of files in a directory, use the following GraphQL query. Replace `path` with the desired directory path. @@ -141,7 +148,7 @@ query { } ``` -#### Response +#### Response: List of Files This query returns the list of files and subdirectories in the specified directory. The response will include the name and type of each item. @@ -204,7 +211,7 @@ The response will include the name and type of each item. ### Fetching a File -#### Query +#### Query: Get File Contents This query receives directory path and send the file contents to user in response. @@ -227,7 +234,7 @@ query { } ``` -#### Response +#### Response: Get File Contents This query returns the name, raw binary blob, and raw text blob of the specified file. The `rawBlob` field contains the file contents @@ -254,7 +261,6 @@ as plain text. } ``` - ## HTTP API Calls The lib microservice also supports making API calls using HTTP POST requests. @@ -282,10 +288,7 @@ POST /lib HTTP/1.1 Host: localhost:4001 Content-Type: application/json Content-Length: 388 - -{ - "query":"query {\n listDirectory(path: \"user1\") {\n repository {\n tree {\n blobs {\n edges {\n node {\n name\n type\n }\n }\n }\n trees {\n edges {\n node {\n name\n type\n }\n }\n }\n }\n }\n }\n}" -} +{"query":"query {\n listDirectory(path: \"user1\") {\n repository {\n tree {\n blobs {\n edges {\n node {\n name\n type\n }\n }\n }\n trees {\n edges {\n node {\n name\n type\n }\n }\n }\n }\n }\n }\n}"} ``` This HTTP POST request will generate the following HTTP response message. @@ -298,7 +301,6 @@ Content-Length: 306 Content-Type: application/json; charset=utf-8 Date: Tue, 26 Sep 2023 20:26:49 GMT X-Powered-By: Express - {"data":{"listDirectory":{"repository":{"tree":{"blobs":{"edges":[]},"trees":{"edges":[{"node":{"name":"data","type":"tree"}},{"node":{"name":"digital twins","type":"tree"}},{"node":{"name":"functions","type":"tree"}},{"node":{"name":"models","type":"tree"}},{"node":{"name":"tools","type":"tree"}}]}}}}}} ``` @@ -314,10 +316,7 @@ POST /lib HTTP/1.1 Host: localhost:4001 Content-Type: application/json Content-Length: 217 - -{ - "query":"query {\n readFile(path: \"user2/data/welcome.txt\") {\n repository {\n blobs {\n nodes {\n name\n rawBlob\n rawTextBlob\n }\n }\n }\n }\n}" -} +{"query":"query {\n readFile(path: \"user2/data/welcome.txt\") {\n repository {\n blobs {\n nodes {\n name\n rawBlob\n rawTextBlob\n }\n }\n }\n }\n}"} ``` ```http @@ -328,6 +327,5 @@ Content-Length: 134 Content-Type: application/json; charset=utf-8 Date: Wed, 27 Sep 2023 09:17:18 GMT X-Powered-By: Express - {"data":{"readFile":{"repository":{"blobs":{"nodes":[{"name":"welcome.txt","rawBlob":"hello world","rawTextBlob":"hello world"}]}}}}} ``` diff --git a/docs/admin/services.md b/docs/admin/services.md index 741695e6b..a96ed4fd8 100644 --- a/docs/admin/services.md +++ b/docs/admin/services.md @@ -51,7 +51,8 @@ docker exec rabbitmq-server rabbitmqctl set_permissions -p "/" ``` 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: +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 @@ -94,7 +95,7 @@ printf "Complete the setup from GUI" The user credentials have also been set in the command as: -**username**: admin +**username**: admin **password**: DTaaSGrafana Remember to change these credentials before starting the docker container. @@ -122,7 +123,7 @@ docker run -d -p 80:8086 \ The user credentials have also been set in the command as: -**username**: dtaas +**username**: dtaas **password**: dtaas1357 Remember to change these credentials before starting the docker container. diff --git a/docs/admin/trial.md b/docs/admin/trial.md index 6acab8eb7..55da68e38 100644 --- a/docs/admin/trial.md +++ b/docs/admin/trial.md @@ -1,4 +1,3 @@ - # Trial Installation The software can be installed either on diff --git a/docs/developer/index.md b/docs/developer/index.md index f4c436779..4db623d3d 100644 --- a/docs/developer/index.md +++ b/docs/developer/index.md @@ -46,27 +46,31 @@ a development workflow is in place. Each developer should follow these steps: 1. Fork of the main repository into your github account. 1. Setup -[Code Climate](https://docs.codeclimate.com/docs/getting-started-with-code-climate) -and -[Codecov](https://docs.codecov.com/docs/quick-start) -for your fork. The codecov does not require secret token -for public repositories. + [Code Climate](https://docs.codeclimate.com/docs/getting-started-with-code-climate) + and + [Codecov](https://docs.codecov.com/docs/quick-start) + for your fork. The codecov does not require secret token + for public repositories. 1. Install git-hooks for the project. 1. Use -[Fork, Branch, PR](https://gun.io/news/2017/01/how-to-github-fork-branch-and-pull-request/) -workflow. -1. Work in your fork and open a PR from your working branch to your `feature/distributed-demo` branch. -The PR will run all the github actions, code climate and codecov checks. + [Fork, Branch, PR](https://gun.io/news/2017/01/how-to-github-fork-branch-and-pull-request/) + workflow. +1. Work in your fork and open a PR from your working + branch to your `feature/distributed-demo` branch. + The PR will run all the github actions, code climate and codecov checks. 1. Resolve all the issues identified in the previous step. 1. If you have access to the -[integration server](https://github.com/INTO-CPS-Association/DTaaS/wiki/DTaaS-Integration-Server), -try your working branch on the integration server. -1. Once changes are verified, a PR should be made to the `feature/distributed-demo` branch of -the upstream -[DTaaS repository](https://github.com/into-cps-association/DTaaS). -1. The PR will be merged after checks by either the project administrators or the maintainers. - -Remember that every PR should be meaningful and satisfies a well-defined user story or improve + [integration server](https://github.com/INTO-CPS-Association/DTaaS/wiki/DTaaS-Integration-Server), + try your working branch on the integration server. +1. Once changes are verified, a PR should be made to + the `feature/distributed-demo` branch of + the upstream + [DTaaS repository](https://github.com/into-cps-association/DTaaS). +1. The PR will be merged after checks by either the + project administrators or the maintainers. + +Remember that every PR should be meaningful and satisfies +a well-defined user story or improve the code quality. ## :eye: Code Quality @@ -74,23 +78,32 @@ the code quality. The project code qualities are measured based on: * Linting issues identified by -[Code Climate](https://codeclimate.com/github/INTO-CPS-Association/DTaaS) + [Code Climate](https://codeclimate.com/github/INTO-CPS-Association/DTaaS) * Test coverage report collected by -[Codecov](https://codecov.io/gh/INTO-CPS-Association/DTaaS) + [Codecov](https://codecov.io/gh/INTO-CPS-Association/DTaaS) * Successful [github actions](https://github.com/INTO-CPS-Association/DTaaS/actions) ### Code Climate -Code Climate performs static analysis, linting and style checks. Quality checks are performed by codeclimate are to ensure the best possible quality of code to add to our project. +Code Climate performs static analysis, linting and style checks. +Quality checks are performed by codeclimate are to ensure the best +possible quality of code to add to our project. -While any new issues introduced in your code would be shown in the PR page itself, to address any specific issue, you can visit the issues or code section of the codeclimate page. +While any new issues introduced in your code would be +shown in the PR page itself, to address any specific issue, +you can visit the issues or code section of the codeclimate page. -It is highly recommended that any code you add does not introduce new quality issues. If they are introduced, they should be fixed immediately using the appropriate suggestions from Code Climate, or in worst case, adding a ignore flag (To be used with caution). +It is highly recommended that any code you add does +not introduce new quality issues. If they are introduced, +they should be fixed immediately using the appropriate suggestions +from Code Climate, or in worst case, adding a ignore flag +(To be used with caution). ### Codecov Codecov keeps track of the test coverage for the entire project. -For information about testing and workflow related to that, please see the [testing page](testing/intro.md). +For information about testing and workflow related to that, +please see the [testing page](testing/intro.md). ### Github Actions diff --git a/docs/developer/servers/lib/lib-ms.md b/docs/developer/servers/lib/lib-ms.md index 740b93e55..268e5a9df 100644 --- a/docs/developer/servers/lib/lib-ms.md +++ b/docs/developer/servers/lib/lib-ms.md @@ -77,11 +77,11 @@ classDiagram sequenceDiagram actor Client actor Traefik - + box LightGreen Library Microservice participant FR as FilesResolver participant FSF as FilesServiceFactory - participant CS as ConfigService + participant CS as ConfigService participant IFS as IFilesService participant LFS as LocalFilesService participant GFS as GitlabFilesService diff --git a/docs/developer/system/architecture.md b/docs/developer/system/architecture.md index a6b38176b..d74e64dbc 100644 --- a/docs/developer/system/architecture.md +++ b/docs/developer/system/architecture.md @@ -3,29 +3,33 @@ ## User Requirements The DTaaS software platform users expect a single platform -to support the complete DT lifecycle. To be more precise, the platform users expect the following features: +to support the complete DT lifecycle. To be more precise, +the platform users expect the following features: 1. **Author** – create different assets of the DT on the -platform itself. This step requires use of some software -frameworks and tools whose sole purpose is to author -DT assets. + platform itself. This step requires use of some software + frameworks and tools whose sole purpose is to author + DT assets. 1. **Consolidate** – consolidate the list of available DT assets -and authoring tools so that user can navigate the library -of reusable assets. This functionality requires support -for discovery of available assets. + and authoring tools so that user can navigate the library + of reusable assets. This functionality requires support + for discovery of available assets. 1. **Configure** – support selection and configuration of -DTs. This functionality also requires support for validation of a given configuration. -1. **Execute** – provision computing infrastructure on demand to support execution of a DT. + DTs. This functionality also requires support for validation + of a given configuration. +1. **Execute** – provision computing infrastructure on demand to + support execution of a DT. 1. **Explore** – interact with a DT and explore the results -stored both inside and outside the platform. Exploration -may lead to analytical insights. + stored both inside and outside the platform. Exploration + may lead to analytical insights. 1. **Save** – save the state of a DT that’s already in the -execution phase. This functionality is required for ondemand saving and re-spawning of DTs. + execution phase. This functionality is required for on + demand saving and re-spawning of DTs. 1. **What-if analysis** – explore alternative scenarios to (i) -plan for an optimal next step, (ii) recalibrate new DT -assets, (iii) automated creation of new DTs or their -assets; these newly created DT assets may be used to -perform scientifically valid experiments. + plan for an optimal next step, (ii) recalibrate new DT + assets, (iii) automated creation of new DTs or their + assets; these newly created DT assets may be used to + perform scientifically valid experiments. 1. **Share** – share a DT with other users of their organisation. ## System Architecture @@ -41,7 +45,7 @@ The gateway is a single point of entry for direct access to the platform services. The gateway is responsible for controlling user access to the microservice components. The service mesh enables discovery of microservices, load balancing and authentication -functionalities. +functionalities. In addition, there are microservices for catering to author, store, explore, configure, execute and scenario analysis requirements. @@ -51,30 +55,29 @@ core requirements of the system. The microservices responsible for satisfying the user requirements are: 1. **The security microservice** implements -role-based access control (RBAC) in the platform. + role-based access control (RBAC) in the platform. 1. **The accounting microservice** is responsible for keeping track of the -platform, DT asset and infrastructure usage. Any licensing, -usage restrictions need to be enforced by the accounting -microservice. Accounting is a pre-requisite to commercialisation of -the platform. - - Due to significant use of external -infrastructure and resources via the platform, the accounting -microservice needs to interface with accounting systems of -the external services. + platform, DT asset and infrastructure usage. Any licensing, + usage restrictions need to be enforced by the accounting + microservice. Accounting is a pre-requisite to commercialisation of + the platform. + Due to significant use of external + infrastructure and resources via the platform, the accounting + microservice needs to interface with accounting systems of + the external services. 1. **The data microservice** is a frontend to all the databases -integrated into the platform. A time-series database and a -graph database are essential. These two databases store timeseries -data from PT, events on PT/DT, commands sent by -DT to PT. The PTs uses these databases even when their -respective DTs are not in the execute phase. + integrated into the platform. A time-series database and a + graph database are essential. These two databases store timeseries + data from PT, events on PT/DT, commands sent by + DT to PT. The PTs uses these databases even when their + respective DTs are not in the execute phase. 1. **The visualisation microservice** is again a frontend to -visualisation software that are natively supported inside the platform. -Any visualisation software running either on external -systems or on client browsers do not need to interact with -this microservice. They can directly use the data provided by -the data microservice. + visualisation software that are natively supported inside the platform. + Any visualisation software running either on external + systems or on client browsers do not need to interact with + this microservice. They can directly use the data provided by + the data microservice. ## C4 Architectural Diagrams diff --git a/docs/developer/system/current-status.md b/docs/developer/system/current-status.md index 2b203a321..dd84e03f8 100644 --- a/docs/developer/system/current-status.md +++ b/docs/developer/system/current-status.md @@ -81,7 +81,7 @@ based on these services. The development priorities for the DTaaS software development team are: * [DT Runner](https://github.com/INTO-CPS-Association/DTaaS/tree/feature/distributed-demo/servers/execution/runner) -(API Interface to DT) + (API Interface to DT) * Multi-user and microservice security * Increased automation of installation procedures * DT Configuration DSL ín the form of YAML schema diff --git a/docs/developer/testing/intro.md b/docs/developer/testing/intro.md index 843b07f05..b90d1bfdd 100644 --- a/docs/developer/testing/intro.md +++ b/docs/developer/testing/intro.md @@ -2,14 +2,14 @@ ## :question: Common Questions on Testing -### What is Software Testing? +### What is Software Testing Software testing is a procedure to investigate the quality of a software product in different scenarios. It can also be stated as the process of verifying and validating that a software program or application works as expected and meets the business and technical requirements that guided design and development. -### Why Software Testing? +### Why Software Testing Software testing is required to point out the defects and errors that were made during different development phases. Software testing also ensures that @@ -19,7 +19,7 @@ One important benefit of software testing is that it facilitates the developers to make incremental changes to source code and make sure that the current changes are not breaking the functionality of the previously existing code. -### What is TDD? +### What is TDD TDD stands for **Test Driven Development**. It is a software development process that relies on the repetition of a very short development cycle: first @@ -30,7 +30,7 @@ The goal of TDD can be viewed as specification and not validation. In other words, it’s one way to think through your requirements or design before your write your functional code. -### What is BDD? +### What is BDD BDD stands for “Behaviour Driven Development”. It is a software development process that emerged from TDD. It includes the practice of writing tests first, @@ -51,7 +51,7 @@ 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: -### [Unit Tests](https://martinfowler.com/articles/practical-test-pyramid.html#UnitTests) +### [Unit Tests](https://martinfowler.com/articles/practical-test-pyramid.html#UnitTests) Unit testing is a level of software testing where individual units/ components of a software are tested. The objective of Unit Testing is to isolate @@ -63,12 +63,17 @@ method stubs, mock objects, and spies can be used to assist testing a module in #### Benefits of Unit Testing * Unit testing increases confidence in changing/ maintaining code. -If good unit tests are written and if they are run every time any code is changed, -we will be able to promptly catch any defects introduced due to the change. -* If codes are already made less interdependent to make unit testing possible, -the unintended impact of changes to any code is less. -* The cost, in terms of time, effort and money, of fixing a defect detected during -unit testing is lesser in comparison to that of defects detected at higher levels. + If good unit tests are written and if they are run every time + any code is changed, + we will be able to promptly catch any defects introduced due + to the change. +* If codes are already made less interdependent to make unit + testing possible, + the unintended impact of changes to any code is less. +* The cost, in terms of time, effort and money, of fixing a + defect detected during + unit testing is lesser in comparison to that of defects + detected at higher levels. #### Unit Tests in DTaaS @@ -76,7 +81,7 @@ Each component DTaaS project uses unique technology stack. Thus the packages used for unit tests are different. Please check the `test/` directory of a component to figure out the unit test packages used. -### [Integration tests](https://martinfowler.com/articles/practical-test-pyramid.html#IntegrationTests) +### [Integration tests](https://martinfowler.com/articles/practical-test-pyramid.html#IntegrationTests) Integration testing is the phase in software testing in which individual software modules are combined and tested as a group. In DTaaS, we use diff --git a/docs/index.md b/docs/index.md index 4950a9b47..f11b7c38f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,12 +3,15 @@ The Digital Twin as a Service (DTaaS) software platform is useful to **Build, Use and Share** digital twins (DTs). -:mechanical_arm: **Build**: The DTs are built on the software platform +:mechanical_arm: **Build**: The +DTs are built on the software platform using the reusable DT components available on the platform. -:office_worker: :factory_worker: **Use**: Use the DTs on the software platform. +:office_worker: :factory_worker: **Use**: Use +the DTs on the software platform. -:handshake: **Share**: Share ready to use DTs with other users. +:handshake: **Share**: Share ready to use DTs +with other users. It is also possible to share the services offered by one DT with other users. There is an overview of the software available in the form of @@ -18,6 +21,13 @@ and [feature walkthrough](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/vid ## License -This software is owned by [The INTO-CPS Association](https://into-cps.org/) and is available under [the INTO-CPS License](LICENSE.md). +This software is owned by +[The INTO-CPS Association](https://into-cps.org/) +and is available under [the INTO-CPS License](LICENSE.md). -The DTaaS software platform uses [Træfik](https://github.com/traefik/traefik), [ML Workspace](https://github.com/ml-tooling/ml-workspace), [Grafana](https://github.com/grafana/grafana), [InfluxDB](https://github.com/influxdata/influxdb) and [RabbitMQ](https://github.com/rabbitmq/rabbitmq-server) open-source components. These software components have their own licenses. +The DTaaS software platform uses [Træfik](https://github.com/traefik/traefik), +[ML Workspace](https://github.com/ml-tooling/ml-workspace), +[Grafana](https://github.com/grafana/grafana), +[InfluxDB](https://github.com/influxdata/influxdb) and +[RabbitMQ](https://github.com/rabbitmq/rabbitmq-server) open-source components. +These software components have their own licenses. diff --git a/docs/thanks.md b/docs/thanks.md index b1705f214..6374a4cd3 100644 --- a/docs/thanks.md +++ b/docs/thanks.md @@ -1,5 +1,4 @@ - -## Contributors +# Contributors [code contributors](https://github.com/INTO-CPS-Association/DTaaS/graphs/contributors) @@ -11,7 +10,10 @@ Henrik Ejersbo, Tanusree Roy, Farshid Naseri ## Documentation -1. Talasila, P., Gomes, C., Mikkelsen, P. H., Arboleda, S. G., Kamburjan, E., & Larsen, P. G. (2023). [Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users](https://arxiv.org/abs/2305.07244). arXiv preprint arXiv:2305.07244. +1. Talasila, P., Gomes, C., Mikkelsen, P. H., Arboleda, S. G., Kamburjan, + E., & Larsen, P. G. (2023). + [Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users](https://arxiv.org/abs/2305.07244). + arXiv preprint arXiv:2305.07244. 1. Astitva Sehgal 1. Tanusree Roy 1. Farshid Naseri \ No newline at end of file diff --git a/docs/user/digital-twins/create.md b/docs/user/digital-twins/create.md index 033cfafd0..ffe48b663 100644 --- a/docs/user/digital-twins/create.md +++ b/docs/user/digital-twins/create.md @@ -1,10 +1,10 @@ - # Create a Digital Twin -The first step in digital twin creation is to use the available assets -in your workspace. If you have assets / files in your computer that need -to be available in the DTaaS workspace, then please follow the instructions -provided in [library assets](../servers/lib/assets.md). +The first step in digital twin creation is to use the available +assets in your workspace. If you have assets / files +in your computer that need to be available in the DTaaS workspace, +then please follow the instructions provided in +[library assets](../servers/lib/assets.md). There are dependencies among the library assets. These dependencies are shown below. @@ -37,7 +37,6 @@ The only requirement is the ability to run the DT from either commandline or desktop. !!! tip - If you are stepping into the world of Digital Twins, you might not have distinct digital twin assets. You are likely to have one directory of everything in which you run your digital twin. In such a case we @@ -116,14 +115,11 @@ responsible for lifecycle management of this digital twin. The [lifecycle page](lifecycle.md) provides more explanation on these programs. !!! Abstract "Execution of a Digital Twin" - A frequent question arises on the run time characteristics of a digital twin. The natural intuition is to say that a digital twin must operate as long as its physical twin is in operation. - **If a digital twin runs for a finite time and then ends, can it be called a digital twin?** - **The answer is a resounding YES**. The Industry 4.0 usecases seen among SMEs have digital twins that run for a finite time. These digital twins are often run at the discretion of the user. @@ -131,28 +127,28 @@ The [lifecycle page](lifecycle.md) provides more explanation on these programs. **You can run this digital twin by**, 1. Go to Workbench tools page of the DTaaS website and open VNC Desktop. -This opens a new tab in your browser + This opens a new tab in your browser 1. A page with VNC Desktop and a connect button comes up. Click on Connect. -You are now connected to the Linux Desktop of your workspace. + You are now connected to the Linux Desktop of your workspace. 1. Open a Terminal (black rectangular icon in the top left region of your tab) -and type the following commands. + and type the following commands. 1. Download the -[example files](https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip) + [example files](https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip) - ```sh - $wget https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip - $unzip main.zip - ``` + ```sh + $wget https://github.com/INTO-CPS-Association/DTaaS-examples/archive/refs/heads/main.zip + $unzip main.zip + ``` 1. Open a file browser and copy the files from this uncompressed folder -into your workspace folder (`/workspace`). Make sure that the file placement -matches the one given above. + into your workspace folder (`/workspace`). Make sure that the file placement + matches the one given above. 1. Go to the digital twin directory and run - ``` - $cd /workspace/digital twins/mass-spring-damper - $lifecycle/execute - ``` + ``` + $cd /workspace/digital twins/mass-spring-damper + $lifecycle/execute + ``` - The last command executes the mass-spring-damper digital twin and stores - the co-simulation output in `data/mass-spring-damper/output`. + The last command executes the mass-spring-damper digital twin and stores + the co-simulation output in `data/mass-spring-damper/output`. diff --git a/docs/user/digital-twins/lifecycle.md b/docs/user/digital-twins/lifecycle.md index 0bf0e8d98..45c05b17c 100644 --- a/docs/user/digital-twins/lifecycle.md +++ b/docs/user/digital-twins/lifecycle.md @@ -99,8 +99,9 @@ if deemed necessary. printf "operation is not supported on this digital twin" ``` -The lifecycle programs can call other programs in the code base. In the case of -`lifecycle/terminate` program, it is calling another script to do the necessary job. +The lifecycle programs can call other programs in the code base. +In the case of `lifecycle/terminate` program, it is calling another +script to do the necessary job. ```bash title="lifecycle/terminate" #!/bin/bash diff --git a/docs/user/examples/incubator/README.md b/docs/user/examples/incubator/README.md index 16e50d86b..f4d96e337 100644 --- a/docs/user/examples/incubator/README.md +++ b/docs/user/examples/incubator/README.md @@ -1,50 +1,49 @@ +# Incubator Demo + Installation of required python packages for the Incubator demo ```bash pip install pyhocon pip install influxdb_client -pip install scipy -pip install pandas -pip install pika -pip install oomodelling -pip install control -pip install filterpy -pip install sympy -pip install docker +pip install scipy +pip install pandas +pip install pika +pip install oomodelling +pip install control +pip install filterpy +pip install sympy +pip install docker ``` start rabbitmq server and create a rabbitmq account with, ```txt -name: incubator -password:incubator +name: incubator +password:incubator with access to the virtual host "/" ``` ```bash -docker run -d \ - --name rabbitmq-server \ - -p 15672:15672 -p 5672:5672 \ - rabbitmq:3-management - +docker run -d --name rabbitmq-server -p 15672:15672 -p 5672:5672 rabbitmq:3-management docker exec rabbitmq-server rabbitmqctl add_user incubator incubator docker exec rabbitmq-server rabbitmqctl set_permissions -p "/" incubator ".*" ".*" ".*" ``` -Access InfluxDB running on another machine. Remember that InfluxDB works only on a distinct sub-domain name like `influx.foo.com`, but not on `foo.com/influx`. +Access InfluxDB running on another machine. +Remember that InfluxDB works only on a distinct sub-domain +name like `influx.foo.com`, but not on `foo.com/influx`. ```bash ssh -i /vagrant/vagrant -fNT -L 40000:localhost:80 vagrant@influx.server2.com ``` - -Update the rabbitmq-server and influxdb configuration in +Update the rabbitmq-server and influxdb configuration in ```bash /home/vagrant/dt/1/incubator/example_digital-twin_incubator/software/startup.conf ``` -select (comment / uncomment) functions in +select (comment / uncomment) functions in ```bash /home/vagrant/dt/1/incubator/example_digital-twin_incubator/software/startup/start_all_services.py diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 84f719a6b..799d65a43 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -1 +1,3 @@ +# DTaaS examples + The examples are hosted in [DTaaS examples repository](https://github.com/INTO-CPS-Association/DTaaS-examples) \ No newline at end of file diff --git a/docs/user/features.md b/docs/user/features.md index 94eb3ebb6..863064ca9 100644 --- a/docs/user/features.md +++ b/docs/user/features.md @@ -4,22 +4,31 @@ The DTaaS software platform provides certain advantages to users: -* Support for different kinds of Digital Twins - CFD, Simulink, co-simulation, FEM, ROM, ML etc. +* 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 * Collaboration and reuse -* Private workspaces for authoring and verification of reusable assets, trial run DTs +* Private workspaces for authoring and verification + of reusable assets, trial run DTs * Cost effectiveness ## Software Features -Each installation of DTaaS platform comes with the features highlighted in the following picture. +Each installation of DTaaS platform comes with +the features highlighted in the following picture. ![Features](current-status.png) -All the users have dedicated workspaces. These workspaces are dockerized versions of Linux Desktops. The user desktops are isolated so the installations and customizations done in one user workspace do not effect the other user workspaces. +All the users have dedicated workspaces. +These workspaces are dockerized versions of Linux Desktops. +The user desktops are isolated so the installations and +customizations done in one user workspace do not effect the +other user workspaces. -Each user workspace comes with some development tools pre-installed. These tools are directly accessible from web browser. The following tools are available at present: +Each user workspace comes with some development tools pre-installed. +These tools are directly accessible from web browser. +The following tools are available at present: | Tool | Advantage | |:---|:---| @@ -28,10 +37,12 @@ Each user workspace comes with some development tools pre-installed. These tools | VS Code in the browser | A popular IDE for software development. Users can develop their digital twin-related assets here. | | ungit | An interactive git client. Users can work with git repositories from web browser | +In addition, users have access to xfce-based remote desktop via VNC client. +The VNC client is available right in the web browser. +The xfce supported desktop software can also be run in their workspace. -In addition, users have access to xfce-based remote desktop via VNC client. The VNC client is available right in the web browser. The xfce supported desktop software can also be run in their workspace. - -The DTaaS software platform has some pre-installed services available. The currently available services are: +The DTaaS software platform has some pre-installed services available. +The currently available services are: | Service | Advantage | |:---|:---| @@ -40,6 +51,12 @@ The DTaaS software platform has some pre-installed services available. The curre | Grafana | Visualization dashboards for their digital twins. | | 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 with both the internal and external services. +In addition, the workspaces are connected to the Internet so +all the Digital Twins run within their workspace can interact +with both the internal and external services. -The users can publish and reuse the digital twin assets available on the platform. In addition, users can run their digital twins and make these live digital twins available as services to their clients. The clients need not be users of the DTaaS software installation. +The users can publish and reuse the digital twin assets +available on the platform. In addition, users can run their +digital twins and make these live digital twins available as +services to their clients. The clients need not be users of +the DTaaS software installation. diff --git a/docs/user/motivation.md b/docs/user/motivation.md index 8f215e0bc..f7c573b24 100644 --- a/docs/user/motivation.md +++ b/docs/user/motivation.md @@ -17,7 +17,8 @@ In addition, how can the DT software platforms: There are quite a few solutions proposed in the recent past to solve this problem. Some of them are: -* Focus on data from Physical Twins (PTs) to perform analysis, diagnosis, planning etc… +* Focus on data from Physical Twins (PTs) to + perform analysis, diagnosis, planning etc… * Share DT assets across the upstream, downstream etc…. * Evaluate different models of PT * DevOps for Cyber Physical Systems (CPS) diff --git a/docs/user/servers/lib/LIB-MS.md b/docs/user/servers/lib/LIB-MS.md index 4ca90eb70..98702993b 100644 --- a/docs/user/servers/lib/LIB-MS.md +++ b/docs/user/servers/lib/LIB-MS.md @@ -1,17 +1,26 @@ # Library Microservice -:fontawesome-solid-circle-info: **The library microservice provides an API interface to reusable assets library. This is only for expert users who need to integrate the DTaaS with their own IT systems. Regular users can safely skip this page.** +:fontawesome-solid-circle-info: **The library microservice provides** +**an API interface to reusable assets library.** +**This is only for expert users who need to integrate the DTaaS** +**with their own IT systems. Regular users can safely skip this page.** - -The lib microservice is responsible for handling and serving the contents of library assets of the DTaaS platform. It provides API endpoints for clients to query, and fetch these assets. +The lib microservice is responsible for handling and serving +the contents of library assets of the DTaaS platform. +It provides API endpoints for clients to query, and fetch these assets. This document provides instructions for using the library microservice. -Please see [assets](assets.md) for a suggested storage conventions of your library assets. +Please see [assets](assets.md) for a suggested storage +conventions of your library assets. -Once the assets are stored in the library, you can access the server's endpoint by typing in the following URL: `http://foo.com/lib`. +Once the assets are stored in the library, +you can access the server's endpoint by typing +in the following URL: `http://foo.com/lib`. -The URL opens a graphql playground. You can check the query schema and try sample queries here. You can also send graphql queries as HTTP POST requests and get responses. +The URL opens a graphql playground. +You can check the query schema and try sample queries here. +You can also send graphql queries as HTTP POST requests and get responses. ## API Queries @@ -20,7 +29,8 @@ The library microservice services two API calls: * Provide a list of contents for a directory * Fetch a file from the available files -The API calls are accepted over GraphQL and HTTP API end points. The format of the accepted queries are: +The API calls are accepted over GraphQL and HTTP API end points. +The format of the accepted queries are: ### Provide list of contents for a directory @@ -28,7 +38,7 @@ To retrieve a list of files in a directory, use the following GraphQL query. Replace `path` with the desired directory path. -send requests to: https://foo.com/lib +send requests to: https://foo.com/lib === "GraphQL Query" @@ -57,6 +67,7 @@ send requests to: https://foo.com/lib } } } + ``` === "GraphQL Response" @@ -115,6 +126,7 @@ send requests to: https://foo.com/lib } } } + ``` === "HTTP Request" @@ -128,22 +140,21 @@ send requests to: https://foo.com/lib { "query":"query {\n listDirectory(path: \"user1\") {\n repository {\n tree {\n blobs {\n edges {\n node {\n name\n type\n }\n }\n }\n trees {\n edges {\n node {\n name\n type\n }\n }\n }\n }\n }\n }\n}" } + ``` === "HTTP Response" - ``` http-response - HTTP/1.1 200 OK - Access-Control-Allow-Origin: * - Connection: close - Content-Length: 306 - Content-Type: application/json; charset=utf-8 - Date: Tue, 26 Sep 2023 20:26:49 GMT - X-Powered-By: Express - - {"data":{"listDirectory":{"repository":{"tree":{"blobs":{"edges":[]},"trees":{"edges":[{"node":{"name":"data","type":"tree"}},{"node":{"name":"digital twins","type":"tree"}},{"node":{"name":"functions","type":"tree"}},{"node":{"name":"models","type":"tree"}},{"node":{"name":"tools","type":"tree"}}]}}}}}} - - ``` +``` http-response +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Connection: close +Content-Length: 306 +Content-Type: application/json; charset=utf-8 +Date: Tue, 26 Sep 2023 20:26:49 GMT +X-Powered-By: Express +{"data":{"listDirectory":{"repository":{"tree":{"blobs":{"edges":[]},"trees":{"edges":[{"node":{"name":"data","type":"tree"}},{"node":{"name":"digital twins","type":"tree"}},{"node":{"name":"functions","type":"tree"}},{"node":{"name":"models","type":"tree"}},{"node":{"name":"tools","type":"tree"}}]}}}}}} +``` ### Fetch a file from the available files @@ -154,70 +165,69 @@ with content of `hello world`. === "GraphQL Request" - ```graphql-request - query { - readFile(path: "user2/data/sample.txt") { - repository { - blobs { - nodes { - name - rawBlob - rawTextBlob - } - } +```graphql-request +query { + readFile(path: "user2/data/sample.txt") { + repository { + blobs { + nodes { + name + rawBlob + rawTextBlob } } } - ``` + } +} +``` === "GraphQL Response" - ```graphql-response - { - "data": { - "readFile": { - "repository": { - "blobs": { - "nodes": [ - { - "name": "sample.txt", - "rawBlob": "hello world", - "rawTextBlob": "hello world" - } - ] +```graphql-response +{ + "data": { + "readFile": { + "repository": { + "blobs": { + "nodes": [ + { + "name": "sample.txt", + "rawBlob": "hello world", + "rawTextBlob": "hello world" } - } + ] } } } - ``` + } +} +``` === "HTTP Request" - ```http-request - POST /lib HTTP/1.1 - Host: foo.com - Content-Type: application/json - Content-Length: 217 - - { - "query":"query {\n readFile(path: \"user2/data/welcome.txt\") {\n repository {\n blobs {\n nodes {\n name\n rawBlob\n rawTextBlob\n }\n }\n }\n }\n}" - } - ``` +```http-request +POST /lib HTTP/1.1 +Host: foo.com +Content-Type: application/json +Content-Length: 217 +{ + "query":"query {\n readFile(path: \"user2/data/welcome.txt\") {\n repository {\n blobs {\n nodes {\n name\n rawBlob\n rawTextBlob\n }\n }\n }\n }\n}" +} +``` === "HTTP Response" - ```http-response - HTTP/1.1 200 OK - Access-Control-Allow-Origin: * - Connection: close - Content-Length: 134 - Content-Type: application/json; charset=utf-8 - Date: Wed, 27 Sep 2023 09:17:18 GMT - X-Powered-By: Express - - {"data":{"readFile":{"repository":{"blobs":{"nodes":[{"name":"welcome.txt","rawBlob":"hello world","rawTextBlob":"hello world"}]}}}}} - - ``` - -The _path_ refers to the file path to look at: For example, _user1_ looks at files of **user1**; _user1/functions_ looks at contents of _functions/_ directory. +```http-response +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Connection: close +Content-Length: 134 +Content-Type: application/json; charset=utf-8 +Date: Wed, 27 Sep 2023 09:17:18 GMT +X-Powered-By: Express +{"data":{"readFile":{"repository":{"blobs":{"nodes":[{"name":"welcome.txt","rawBlob":"hello world","rawTextBlob":"hello world"}]}}}}} +``` + +The _path_ refers to the file path to look at: +For example, _user1_ looks at files of +**user1**; _user1/functions_ looks at contents of _functions/_ directory. diff --git a/docs/user/servers/lib/assets.md b/docs/user/servers/lib/assets.md index db25364af..6354f84a6 100644 --- a/docs/user/servers/lib/assets.md +++ b/docs/user/servers/lib/assets.md @@ -1,6 +1,8 @@ # Reusable Assets -The reusability of digital twin assets makes it easy for users to work with the digital twins. The reusability of assets is a fundamental feature of the platform. +The reusability of digital twin assets makes it easy for +users to work with the digital twins. The reusability of +assets is a fundamental feature of the platform. ## Kinds of Reusable Assets @@ -8,34 +10,68 @@ The DTaaS software categorizes all the reusable library assets into five categor ![Categories of Library Assets](library-assets.png) - ### Functions -The functions responsible for pre- and post-processing of: data inputs, data outputs, control outputs. The data science libraries and functions can be used to create useful function assets for the platform. -In some cases, Digital Twin models require calibration prior to their use; functions written by domain experts along with right data inputs can make model calibration an achievable goal. Another use of functions is to process the sensor and actuator data of both Physical Twins and Digital Twins. +The functions responsible for pre- and post-processing of: +data inputs, data outputs, control outputs. The data science +libraries and functions can be used to create useful function +assets for the platform. +In some cases, Digital Twin models require calibration prior +to their use; functions written by domain experts along with +right data inputs can make model calibration an achievable goal. +Another use of functions is to process the sensor and actuator +data of both Physical Twins and Digital Twins. ### Data -The data sources and sinks available to a digital twins. Typical examples of data sources are sensor measurements from Physical Twins, and test data provided by manufacturers for calibration of models. Typical examples of data sinks are visualization software, external users and data storage services. There exist special outputs such as events, and commands which are akin to control outputs from a Digital Twin. These control outputs usually go to Physical Twins, but they can also go to another Digital Twin. +The data sources and sinks available to a digital twins. +Typical examples of data sources are sensor measurements from +Physical Twins, and test data provided by manufacturers for +calibration of models. Typical examples of data sinks are visualization +software, external users and data storage services. There exist special +outputs such as events, and commands which are akin to control outputs +from a Digital Twin. These control outputs usually go to Physical Twins, +but they can also go to another Digital Twin. ### Models -The model assets are used to describe different aspects of Physical Twins and their environment, at different levels of abstraction. Therefore, it is possible to have multiple models for the same Physical Twin. For example, a flexible robot used in a car production plant may have structural model(s) which will be useful in tracking the wear and tear of parts. The same robot can have a behavioural model(s) describing the safety guarantees provided by the robot manufacturer. The same robot can also have a functional model(s) describing the part manufacturing capabilities of the robot. +The model assets are used to describe different aspects of Physical Twins +and their environment, at different levels of abstraction. Therefore, it +is possible to have multiple models for the same Physical Twin. +For example, a flexible robot used in a car production plant may have +structural model(s) which will be useful in tracking the wear and tear +of parts. The same robot can have a behavioural model(s) describing the +safety guarantees provided by the robot manufacturer. The same robot +can also have a functional model(s) describing the part manufacturing +capabilities of the robot. ### Tools -The software tool assets are software used to create, evaluate and analyze models. These tools are executed on top of a computing platforms, i.e., an operating system, or virtual machines like Java virtual machine, or inside docker containers. The tools tend to be platform specific, making them less reusable than models. -A tool can be packaged to run on a local or distributed virtual machine environments thus allowing selection of most suitable execution environment for a Digital Twin. -Most models require tools to evaluate them in the context of data inputs. -There exist cases where executable packages are run as binaries in a computing environment. Each of these packages are a pre-packaged combination of models and tools put together to create a ready to use Digital Twins. +The software tool assets are software used to create, evaluate and +analyze models. These tools are executed on top of a computing +platforms, i.e., an operating system, or virtual machines like +Java virtual machine, or inside docker containers. +The tools tend to be platform specific, making them less reusable than models. +A tool can be packaged to run on a local or distributed virtual +machine environments thus allowing selection of most suitable +execution environment for a Digital Twin. +Most models require tools to evaluate them in the context of data inputs. +There exist cases where executable packages are run as binaries +in a computing environment. Each of these packages are a pre-packaged +combination of models and tools put together to create a ready +to use Digital Twins. ### Digital Twins -These are ready to use digital twins created by one or more users. These digital twins can be reconfigured later for specific use cases. +These are ready to use digital twins created by one or more users. +These digital twins can be reconfigured later for specific use cases. ## File System Structure -Each user has their assets put into five different directories named above. In addition, there will also be common library assets that all users have access to. A simplified example of the structure is as follows: +Each user has their assets put into five different +directories named above. In addition, there will also be +common library assets that all users have access to. +A simplified example of the structure is as follows: ```text workspace/ @@ -89,10 +125,16 @@ workspace/ ``` !!! tip + The DTaaS is agnostic to the format of your assets. + The only requirement is that they are files which can + be uploaded on the Library page. Any directories can be + compressed as one file and uploaded. You can decompress + the file into a directory from a Terminal or xfce Desktop + available on the Workbench page. - The DTaaS is agnostic to the format of your assets. The only requirement is that they are files which can be uploaded on the Library page. Any directories can be compressed as one file and uploaded. You can decompress the file into a directory from a Terminal or xfce Desktop available on the Workbench page. - -A recommended file system structure for storing assets is also available in [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples). +A recommended file system structure for storing assets is also +available in +[DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples). ## Create Assets @@ -100,7 +142,11 @@ 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. +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 @@ -108,4 +154,10 @@ Users can upload assets into their workspace using Library page of the website. ![Library Page](../../website/library.png) -You can go into a directory and click on the **upload** button to upload a file or a directory into your workspace. This asset is then available in all the workbench tools you can use. 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. +You can go into a directory and click on the **upload** +button to upload a file or a directory into your workspace. +This asset is then available in all the workbench tools you can use. +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. diff --git a/docs/user/website/index.md b/docs/user/website/index.md index a31f93d96..cda1291d8 100644 --- a/docs/user/website/index.md +++ b/docs/user/website/index.md @@ -49,18 +49,15 @@ in their workspace. The functions responsible for pre- and post-processing of: data inputs, data outputs, control outputs. The data science libraries and functions can be used to create useful function assets for the platform. - In some cases, Digital Twin models require calibration prior to their use; functions written by domain experts along with right data inputs can make model calibration an achievable goal. Another use of functions is to process the sensor and actuator data of both Physical Twins and Digital Twins. - ``` ??? Data tip The data sources and sinks available to a digital twins. Typical examples of data sources are sensor measurements from Physical Twins, and test data provided by manufacturers for calibration of models. - Typical examples of data sinks are visualization software, external users and data storage services. There exist special outputs such as events, and commands which are akin to control outputs from a Digital Twin. @@ -84,11 +81,9 @@ in their workspace. platforms, i.e., an operating system, or virtual machines like Java virtual machine, or inside docker containers. The tools tend to be platform specific, making them less reusable than models. - A tool can be packaged to run on a local or distributed virtual machine environments thus allowing selection of most suitable execution - environment for a Digital Twin. - + environment for a Digital Twin. Most models require tools to evaluate them in the context of data inputs. There exist cases where executable packages are run as binaries in a computing environment. Each of these packages are a pre-packaged @@ -105,13 +100,11 @@ data, functions, models, tools and digital twins. ??? Common Assets tip The common directory again has four sub-directories: - * data * functions * models * tools * digital twins - The assets common to all users are placed in **common**. The items used by more than one user are placed in **common**. The items in @@ -134,7 +127,6 @@ digital twin. You can see more explanation on the [life cycle phases of digital twin](../digital-twins/lifecycle.md). ??? Create tip - Create digital twins from tools provided within user workspaces. Each digital twin will have one directory. It is suggested that user provide one bash shell script to run their digital twin. Users can @@ -142,7 +134,6 @@ the [life cycle phases of digital twin](../digital-twins/lifecycle.md). Workbench page. ??? Execute tip - Digital twins are executed from within user workspaces. The given bash script gets executed from digital twin directory. Terminal-based digital twins can be executed from VSCode and graphical digital twins @@ -150,7 +141,13 @@ the [life cycle phases of digital twin](../digital-twins/lifecycle.md). in the data directory. ??? Analyze tip - + The analysis of digital twins requires running + of digital twin script from user workspace. + The execution results placed within data directory + are processed by analysis scripts and results are placed + back in the data directory. These scripts can either be + executed from VSCode and graphical results or can be + executed from VNC GUI. The analysis of digital twins requires running of digital twin script from user workspace. The execution results placed within data directory are processed by analysis scripts and results are placed back in @@ -174,7 +171,9 @@ in new browser are: ![Workbench Tools](workbench_tools.png) !!! Bug - + The Terminal hyperlink does not always work reliably. + If you want terminal. Please use the tools dropdown + in the Jupyter Notebook. The Terminal hyperlink does not always work reliably. If you want terminal. Please use the tools dropdown in the Jupyter Notebook. diff --git a/servers/config/gateway/README.md b/servers/config/gateway/README.md index 8d26efa1b..dfb3159a7 100644 --- a/servers/config/gateway/README.md +++ b/servers/config/gateway/README.md @@ -49,7 +49,9 @@ You can update the configuration in this file to reflect your local setup. See [Traefik help docs](https://doc.traefik.io/traefik/providers/file/) for more information. -The routes / URLs need to be updated for your local setup. The current version of software only works for non-localhost setting, i.e. URL other than the localhost. Here is an example, +The routes / URLs need to be updated for your local setup. +The current version of software only works for non-localhost +setting, i.e. URL other than the localhost. Here is an example, | Route / URL | Background Service | Service URL | | :------------ | :----------------- | :------------- | diff --git a/servers/execution/runner/LICENSE.md b/servers/execution/runner/LICENSE.md index be60b871f..5e134141b 100644 --- a/servers/execution/runner/LICENSE.md +++ b/servers/execution/runner/LICENSE.md @@ -1,34 +1,39 @@ +# License + --- Start of Definition of INTO-CPS Association Public License --- /* - * This file is part of the INTO-CPS Association. - * - * Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), - * c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, - * Finlandsgade 22, 8200 Aarhus N, Denmark. - * - * All rights reserved. - * - * THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR - * THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. - * ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES - * RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR - * THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. - * - * The INTO-CPS tool suite software and the INTO-CPS Association - * Public License (ICAPL) are obtained from the INTO-CPS Association, either - * from the above address, from the URLs: http://www.into-cps.org or - * in the INTO-CPS tool suite distribution. - * GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. - * - * This program is distributed WITHOUT ANY WARRANTY; without - * even the implied warranty of MERCHANTABILITY or FITNESS - * FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH - * IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF - * THE INTO-CPS ASSOCIATION PUBLIC LICENSE. - * - * See the full ICAPL conditions for more details. - * + +* This file is part of the INTO-CPS Association. + +* Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), +* c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, +* Finlandsgade 22, 8200 Aarhus N, Denmark. + +* All rights reserved. + +* THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR +* THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. +* ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES +* RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR +* THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. + +* The INTO-CPS tool suite software and the INTO-CPS Association +* Public License (ICAPL) are obtained from the INTO-CPS Association, either +* from the above address, from the URLs: +* http://www.into-cps.org or +* in the INTO-CPS tool suite distribution. +* GNU version 3 is obtained from: +* http://www.gnu.org/copyleft/gpl.html. + +* This program is distributed WITHOUT ANY WARRANTY; without +* even the implied warranty of MERCHANTABILITY or FITNESS +* FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH +* IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF +* THE INTO-CPS ASSOCIATION PUBLIC LICENSE. + +* See the full ICAPL conditions for more details. + */ --- End of INTO-CPS Association Public License Header --- @@ -37,38 +42,47 @@ The ICAPL is a public license for the INTO-CPS tool suite with three modes/alter (GPL, ICA-Internal-EPL, ICA-External-EPL) for use and redistribution, in source and/or binary/object-code form: -* GPL. Any party (member or non-member of the INTO-CPS Association) may use and +* GPL. Any party (member or non-member of the INTO-CPS Association) may use and redistribute INTO-CPS tool suite under GPL version 3. -* Silver Level members of the INTO-CPS Association may also use and redistribute +* Silver Level members of the INTO-CPS Association + may also use and redistribute the INTO-CPS tool suite under ICA-Internal-EPL conditions. -* Gold Level members of the INTO-CPS Association may also use and redistribute +* Gold Level members of the INTO-CPS Association may also use and redistribute The INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions. Definitions of the INTO-CPS Association Public license modes: * GPL = GPL version 3. -* ICA-Internal-EPL = These INTO-CPA Association Public license conditions together with - Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association is only allowed - within the INTO-CPS Association member's own organization (i.e., its own legal entity), - or for a member of the INTO-CPS Association paying a membership fee corresponding to - the size of the organization including all its affiliates, use and redistribution - is allowed within/between its affiliates. - -* ICA-External-EPL = These INTO-CPA Association Public license conditions together with - Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association, or by a Licensed - Third Party Distributor having a redistribution agreement with that member, - to parties external to the INTO-CPS Association member’s own organization (i.e., its own - legal entity) is only allowed in binary/object-code form, except the case of - redistribution to other members the INTO-CPS Association to which source is also - allowed to be distributed. +* ICA-Internal-EPL = These INTO-CPA Association Public + license conditions together with + Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association is only allowed + within the INTO-CPS Association member's own organization + (i.e., its own legal entity), + or for a member of the INTO-CPS Association paying a + membership fee corresponding to + the size of the organization including all its affiliates, use and redistribution + is allowed within/between its affiliates. + +* ICA-External-EPL = These INTO-CPA Association Public license + conditions together with + Externally restricted EPL, i.e., EPL version 1.0 with the + Additional Condition + that use and redistribution by a member of the INTO-CPS Association, or by a Licensed + Third Party Distributor having a redistribution agreement with that member, + to parties external to the INTO-CPS Association member’s + own organization (i.e., its own + legal entity) is only allowed in binary/object-code form, except the case of + redistribution to other members the + INTO-CPS Association to which source is also + allowed to be distributed. [This has the consequence that an external party who wishes to use -the INTO-CPS Association in source form together with its own proprietary software in all +the INTO-CPS Association in source form together +with its own proprietary software in all cases must be a member of the INTO-CPS Association]. In all cases of usage and redistribution by recipients, the following @@ -90,8 +104,10 @@ c) A recipient must clearly indicate its chosen usage mode of ICAPL, in accompanying documentation and in a text file ICA-USAGE-MODE.txt, provided with the distribution. -d) Contributor(s) making a Contribution to the INTO-CPS Association thereby also makes a - Transfer of Contribution Copyright. In return, upon the effective date of +d) Contributor(s) making a Contribution to the + INTO-CPS Association thereby also makes a + Transfer of Contribution Copyright. In return, + upon the effective date of the transfer, ICA grants the Contributor(s) a Contribution License of the Contribution. ICA has the right to accept or refuse Contributions. @@ -108,13 +124,16 @@ ICA-Internal-EPL and ICA-External-EPL. INTO-CPS Association Public License version 1.0, i.e., the license defined here (the text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of Definition of INTO-CPS Association Public License ---", or later versions thereof. +"--- End of Definition of INTO-CPS Association Public License ---", +or later versions thereof. "ICAPL Header" means: INTO-CPS Association Public License Header version 1.2, i.e., the -text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of INTO-CPS Association Public License Header ---, or later versions thereof. +text between "--- Start of Definition of +INTO-CPS Association Public License ---" and +"--- End of INTO-CPS Association Public License Header ---, +or later versions thereof. "Contribution" means: @@ -125,21 +144,26 @@ b) in the case of each subsequent Contributor: i) changes to the INTO-CPS tool suite, and ii) additions to the INTO-CPS tool suite; -where such changes and/or additions to the INTO-CPS tool suite originate from and are +where such changes and/or additions to the +INTO-CPS tool suite originate from and are distributed by that particular Contributor. A Contribution 'originates' from -a Contributor if it was added to the INTO-CPS tool suite by such Contributor itself or +a Contributor if it was added to the INTO-CPS tool +suite by such Contributor itself or anyone acting on such Contributor's behalf. For Contributors licensing the INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions, the following conditions also hold: Contributions do not include additions to the distributed Program which: (i) -are separate modules of software distributed in conjunction with the INTO-CPS tool suite +are separate modules of software distributed in +conjunction with the INTO-CPS tool suite under their own license agreement, (ii) are separate modules which are not derivative works of the INTO-CPS tool suite, and (iii) are separate modules of software distributed in conjunction with the INTO-CPS tool suite under their own license agreement -where these separate modules are merged with (weaved together with) modules of -The INTO-CPS tool suite to form new modules that are distributed as object code or source +where these separate modules are merged with +(weaved together with) modules of +The INTO-CPS tool suite to form new modules that +are distributed as object code or source code under their own license agreement, as allowed under the Additional Condition of internal distribution according to ICA-Internal-EPL and/or Additional Condition for external distribution according to ICA-External-EPL. @@ -147,14 +171,22 @@ Additional Condition for external distribution according to ICA-External-EPL. "Transfer of Contribution Copyright" means that the Contributors of a Contribution transfer the ownership and the copyright of the Contribution to the INTO-CPS Association, the INTO-CPS Association Copyright owner, for -inclusion in the INTO-CPS tool suite. The transfer takes place upon the effective date -when the Contribution is made available on the INTO-CPS Association web site under ICAPL, by +inclusion in the INTO-CPS tool suite. +The transfer takes place upon the effective date +when the Contribution is made available on the INTO-CPS +Association web site under ICAPL, by such Contributors themselves or anyone acting on such Contributors' behalf. -The transfer is free of charge. If the Contributors or the INTO-CPS Association so wish, -an optional Copyright transfer agreement can be signed between the INTO-CPS Association and the Contributors. - -"Contribution License" means a license from the INTO-CPS Association to the Contributors of the Contribution, effective on the date of the Transfer of Contribution Copyright, -where the INTO-CPS Association grants the Contributors a non-exclusive, world-wide, transferable, free of charge, perpetual license, including sublicensing rights, to use, +The transfer is free of charge. If the Contributors or +the INTO-CPS Association so wish, +an optional Copyright transfer agreement can be signed +between the INTO-CPS Association and the Contributors. + +"Contribution License" means a license from the +INTO-CPS Association to the Contributors of the Contribution, +effective on the date of the Transfer of Contribution Copyright, +where the INTO-CPS Association grants the Contributors +a non-exclusive, world-wide, transferable, free of charge, +perpetual license, including sublicensing rights, to use, have used, modify, have modified, reproduce and or have reproduced the contributed material, for business and other purposes, including but not limited to evaluation, development, testing, integration and merging with @@ -166,18 +198,19 @@ the INTO-CPS tool chain. "The Program" means the Contributions distributed in accordance with ICAPL. -"The INTO-CPS tool chain" means the Contributions distributed in accordance with ICAPL. +"The INTO-CPS tool chain" means the Contributions distributed +in accordance with ICAPL. "Recipient" means anyone who receives the INTO-CPS tool chain under ICAPL, including all Contributors. "Licensed Third Party Distributor" means a reseller/distributor having signed -a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS -Association Bylaws, with a Gold Level organizational member which is not an -Affiliate of the reseller/distributor, for distributing a product containing -part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall -only be allowed further redistribution to other resellers if the Gold Level -member is granting such a right to it in the redistribution/resale agreement +a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS +Association Bylaws, with a Gold Level organizational member which is not an +Affiliate of the reseller/distributor, for distributing a product containing +part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall +only be allowed further redistribution to other resellers if the Gold Level +member is granting such a right to it in the redistribution/resale agreement between the Gold Level member and the Licensed Third Party Distributor. "Affiliate" shall mean any legal entity, directly or indirectly, through one @@ -197,7 +230,8 @@ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the -appropriateness of using and distributing the INTO-CPS tool suite and assumes all risks +appropriateness of using and distributing the +INTO-CPS tool suite and assumes all risks associated with its exercise of rights under ICAPL , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability @@ -211,18 +245,22 @@ SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL -SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL +SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. A Contributor licensing the INTO-CPS tool suite under ICA-Internal-EPL or -ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite +ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite in object code form under its own license agreement, provided that: -a) it complies with the terms and conditions of ICAPL; or for the case of -redistribution of the INTO-CPS tool suite together with proprietary code it is a dual -license where the INTO-CPS tool suite parts are distributed under ICAPL compatible -conditions and the proprietary code is distributed under proprietary license +a) it complies with the terms and conditions of ICAPL; +or for the case of +redistribution of the INTO-CPS tool suite together +with proprietary code it is a dual +license where the INTO-CPS tool suite parts are distributed +under ICAPL compatible +conditions and the proprietary code is distributed under +proprietary license conditions; and b) its license agreement: @@ -235,8 +273,10 @@ damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) states that any provisions which differ from ICAPL are offered by that Contributor alone and not by any other party; and - iv) states from where the source code for the INTO-CPS tool suite is available, and -informs licensees how to obtain it in a reasonable manner on or through a + iv) states from where the source code for the +INTO-CPS tool suite is available, and +informs licensees how to obtain it in a +reasonable manner on or through a medium customarily used for software exchange. When the INTO-CPS tool suite is made available in source code form: @@ -258,9 +298,11 @@ This Agreement is governed by the laws of Denmark. The place of jurisdiction for all disagreements related to this Agreement, is Aarhus, Denmark. The EPL 1.0 license definition has been obtained from: -http://www.eclipse.org/legal/epl-v10.html. It is also reproduced in the INTO-CPS distribution. +http://www.eclipse.org/legal/epl-v10.html. +It is also reproduced in the INTO-CPS distribution. The GPL Version 3 license definition has been obtained from -http://www.gnu.org/copyleft/gpl.html. It is also reproduced in the INTO-CPS distribution. +http://www.gnu.org/copyleft/gpl.html. +It is also reproduced in the INTO-CPS distribution. --- End of Definition of INTO-CPS Association Public License --- diff --git a/servers/execution/runner/README.md b/servers/execution/runner/README.md index 4be89aa9e..ee0aa8628 100644 --- a/servers/execution/runner/README.md +++ b/servers/execution/runner/README.md @@ -1,15 +1,18 @@ # :runner: Digital Twin Runner -A utility service to manage the [lifecycle of one digital twin](../../../docs/user/digital-twins/lifecycle.md). -The lifecycle of a digital twin is made of multiple phases. This digital twin runner utility -helps with the managing the execution of lifecycle phases. This utility can be +A utility service to manage the +[lifecycle of one digital twin](../../../docs/user/digital-twins/lifecycle.md). +The lifecycle of a digital twin is made of multiple phases. +This digital twin runner utility +helps with the managing the execution of lifecycle phases. +This utility can be launched in two scenarios: 1. User launches this from commandline and let the utility -manage the lifecycle of one digital twin. -2. Execution infrastructure of Digital Twin as a Service (DTaaS) -launches this utility and instructs it to manage the lifecycle of -one digital twin. + manage the lifecycle of one digital twin. +1. Execution infrastructure of Digital Twin as a Service (DTaaS) + launches this utility and instructs it to manage the lifecycle of + one digital twin. The digital twin runner utility runs as a service and will provide REST API interface to execute lifecycle scripts of a digital twin. @@ -36,7 +39,7 @@ yarn clean # deletes directories "build", "coverage", and "dist" This package need to be published to an npm registry. There after, the package can be installed as a system command. Since publishing to npmjs.org is irrevocable and public, developers are encouraged to setup their own private -npm registry for local development. We recommend using +npm registry for local development. We recommend using [verdaccio](https://verdaccio.org) for this task. The following commands help you create a working private npm registry for development. @@ -47,7 +50,7 @@ npm set registry http://localhost:4873/ yarn config set registry "http://localhost:4873" ``` -You can open `http://localhost:4873` in your browser, login with +You can open `http://localhost:4873` in your browser, login with the user credentials to see the packages published. ### Publish to private registry @@ -70,7 +73,7 @@ for more information. If there is a need to unpublish a package, ex: `@dtaas/runner@0.0.2`, do: ```bash -npm unpublish --registry http://localhost:4873/ @dtaas/runner@0.0.2 +npm unpublish --registry http://localhost:4873/ @dtaas/runner@0.0.2 ``` To install / uninstall this utility for all users, do: @@ -78,7 +81,7 @@ To install / uninstall this utility for all users, do: ```bash sudo npm install --registry http://localhost:4873 -g @dtaas/runner sudo npm list -g # should list @dtaas/runner in the packages -sudo npm remove --global @dtaas/runner +sudo npm remove --global @dtaas/runner ``` ## :rocket: Access the service @@ -104,7 +107,6 @@ for these two sources are: | localhost:3000/lifecycle/phase | _true_ | Always returns _true_ | ||| - ## :balance_scale: License This software is owned by diff --git a/servers/lib/LICENSE.md b/servers/lib/LICENSE.md index be60b871f..a5273233f 100644 --- a/servers/lib/LICENSE.md +++ b/servers/lib/LICENSE.md @@ -1,34 +1,39 @@ +# License + --- Start of Definition of INTO-CPS Association Public License --- /* - * This file is part of the INTO-CPS Association. - * - * Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), - * c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, - * Finlandsgade 22, 8200 Aarhus N, Denmark. - * - * All rights reserved. - * - * THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR - * THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. - * ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES - * RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR - * THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. - * - * The INTO-CPS tool suite software and the INTO-CPS Association - * Public License (ICAPL) are obtained from the INTO-CPS Association, either - * from the above address, from the URLs: http://www.into-cps.org or - * in the INTO-CPS tool suite distribution. - * GNU version 3 is obtained from: http://www.gnu.org/copyleft/gpl.html. - * - * This program is distributed WITHOUT ANY WARRANTY; without - * even the implied warranty of MERCHANTABILITY or FITNESS - * FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH - * IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF - * THE INTO-CPS ASSOCIATION PUBLIC LICENSE. - * - * See the full ICAPL conditions for more details. - * + +* This file is part of the INTO-CPS Association. + +* Copyright (c) 2017-CurrentYear, INTO-CPS Association (ICA), +* c/o Peter Gorm Larsen, Aarhus University, Department of Engineering, +* Finlandsgade 22, 8200 Aarhus N, Denmark. + +* All rights reserved. + +* THIS PROGRAM IS PROVIDED UNDER THE TERMS OF GPL VERSION 3 LICENSE OR +* THIS INTO-CPS ASSOCIATION PUBLIC LICENSE (ICAPL) VERSION 1.0. +* ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES +* RECIPIENT'S ACCEPTANCE OF THE INTO-CPS ASSOCIATION PUBLIC LICENSE OR +* THE GPL VERSION 3, ACCORDING TO RECIPIENTS CHOICE. + +* The INTO-CPS tool suite software and the INTO-CPS Association +* Public License (ICAPL) are obtained from the INTO-CPS Association, either +* from the above address, from the URLs: +* http://www.into-cps.org or +* in the INTO-CPS tool suite distribution. +* GNU version 3 is obtained from: +* http://www.gnu.org/copyleft/gpl.html. + +* This program is distributed WITHOUT ANY WARRANTY; without +* even the implied warranty of MERCHANTABILITY or FITNESS +* FOR A PARTICULAR PURPOSE, EXCEPT AS EXPRESSLY SET FORTH +* IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE CONDITIONS OF +* THE INTO-CPS ASSOCIATION PUBLIC LICENSE. + +* See the full ICAPL conditions for more details. + */ --- End of INTO-CPS Association Public License Header --- @@ -37,38 +42,48 @@ The ICAPL is a public license for the INTO-CPS tool suite with three modes/alter (GPL, ICA-Internal-EPL, ICA-External-EPL) for use and redistribution, in source and/or binary/object-code form: -* GPL. Any party (member or non-member of the INTO-CPS Association) may use and +* GPL. Any party (member or non-member of the INTO-CPS Association) may use and redistribute INTO-CPS tool suite under GPL version 3. -* Silver Level members of the INTO-CPS Association may also use and redistribute +* Silver Level members of the INTO-CPS Association may also + use and redistribute the INTO-CPS tool suite under ICA-Internal-EPL conditions. -* Gold Level members of the INTO-CPS Association may also use and redistribute +* Gold Level members of the INTO-CPS Association may also use and redistribute The INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions. Definitions of the INTO-CPS Association Public license modes: * GPL = GPL version 3. -* ICA-Internal-EPL = These INTO-CPA Association Public license conditions together with - Internally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association is only allowed - within the INTO-CPS Association member's own organization (i.e., its own legal entity), - or for a member of the INTO-CPS Association paying a membership fee corresponding to - the size of the organization including all its affiliates, use and redistribution - is allowed within/between its affiliates. - -* ICA-External-EPL = These INTO-CPA Association Public license conditions together with - Externally restricted EPL, i.e., EPL version 1.0 with the Additional Condition - that use and redistribution by a member of the INTO-CPS Association, or by a Licensed - Third Party Distributor having a redistribution agreement with that member, - to parties external to the INTO-CPS Association member’s own organization (i.e., its own - legal entity) is only allowed in binary/object-code form, except the case of - redistribution to other members the INTO-CPS Association to which source is also - allowed to be distributed. +* ICA-Internal-EPL = These INTO-CPA Association + Public license conditions together with + Internally restricted EPL, i.e., EPL + version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association is only allowed + within the INTO-CPS Association member's own + organization (i.e., its own legal entity), + or for a member of the INTO-CPS Association + paying a membership fee corresponding to + the size of the organization including all its affiliates, use and redistribution + is allowed within/between its affiliates. + +* ICA-External-EPL = These INTO-CPA Association + Public license conditions together with + Externally restricted EPL, i.e., EPL + version 1.0 with the Additional Condition + that use and redistribution by a member of the INTO-CPS Association, or by a Licensed + Third Party Distributor having a redistribution agreement with that member, + to parties external to the INTO-CPS + Association member’s own organization (i.e., its own + legal entity) is only allowed in binary/object-code form, except the case of + redistribution to other members the + INTO-CPS Association to which source is also + allowed to be distributed. [This has the consequence that an external party who wishes to use -the INTO-CPS Association in source form together with its own proprietary software in all +the INTO-CPS Association in source form +together with its own proprietary software in all cases must be a member of the INTO-CPS Association]. In all cases of usage and redistribution by recipients, the following @@ -90,7 +105,8 @@ c) A recipient must clearly indicate its chosen usage mode of ICAPL, in accompanying documentation and in a text file ICA-USAGE-MODE.txt, provided with the distribution. -d) Contributor(s) making a Contribution to the INTO-CPS Association thereby also makes a +d) Contributor(s) making a Contribution + to the INTO-CPS Association thereby also makes a Transfer of Contribution Copyright. In return, upon the effective date of the transfer, ICA grants the Contributor(s) a Contribution License of the Contribution. ICA has the right to accept or refuse Contributions. @@ -108,12 +124,14 @@ ICA-Internal-EPL and ICA-External-EPL. INTO-CPS Association Public License version 1.0, i.e., the license defined here (the text between "--- Start of Definition of INTO-CPS Association Public License ---" and -"--- End of Definition of INTO-CPS Association Public License ---", or later versions thereof. +"--- End of Definition of INTO-CPS +Association Public License ---", or later versions thereof. "ICAPL Header" means: INTO-CPS Association Public License Header version 1.2, i.e., the -text between "--- Start of Definition of INTO-CPS Association Public License ---" and +text between "--- Start of Definition of +INTO-CPS Association Public License ---" and "--- End of INTO-CPS Association Public License Header ---, or later versions thereof. "Contribution" means: @@ -125,21 +143,25 @@ b) in the case of each subsequent Contributor: i) changes to the INTO-CPS tool suite, and ii) additions to the INTO-CPS tool suite; -where such changes and/or additions to the INTO-CPS tool suite originate from and are +where such changes and/or additions to the +INTO-CPS tool suite originate from and are distributed by that particular Contributor. A Contribution 'originates' from -a Contributor if it was added to the INTO-CPS tool suite by such Contributor itself or +a Contributor if it was added to the INTO-CPS tool suite +by such Contributor itself or anyone acting on such Contributor's behalf. For Contributors licensing the INTO-CPS tool suite under ICA-Internal-EPL or ICA-External-EPL conditions, the following conditions also hold: Contributions do not include additions to the distributed Program which: (i) -are separate modules of software distributed in conjunction with the INTO-CPS tool suite +are separate modules of software distributed in +conjunction with the INTO-CPS tool suite under their own license agreement, (ii) are separate modules which are not derivative works of the INTO-CPS tool suite, and (iii) are separate modules of software distributed in conjunction with the INTO-CPS tool suite under their own license agreement where these separate modules are merged with (weaved together with) modules of -The INTO-CPS tool suite to form new modules that are distributed as object code or source +The INTO-CPS tool suite to form new modules that +are distributed as object code or source code under their own license agreement, as allowed under the Additional Condition of internal distribution according to ICA-Internal-EPL and/or Additional Condition for external distribution according to ICA-External-EPL. @@ -147,14 +169,22 @@ Additional Condition for external distribution according to ICA-External-EPL. "Transfer of Contribution Copyright" means that the Contributors of a Contribution transfer the ownership and the copyright of the Contribution to the INTO-CPS Association, the INTO-CPS Association Copyright owner, for -inclusion in the INTO-CPS tool suite. The transfer takes place upon the effective date -when the Contribution is made available on the INTO-CPS Association web site under ICAPL, by +inclusion in the INTO-CPS tool suite. +The transfer takes place upon the effective date +when the Contribution is made available on the INTO-CPS +Association web site under ICAPL, by such Contributors themselves or anyone acting on such Contributors' behalf. -The transfer is free of charge. If the Contributors or the INTO-CPS Association so wish, -an optional Copyright transfer agreement can be signed between the INTO-CPS Association and the Contributors. - -"Contribution License" means a license from the INTO-CPS Association to the Contributors of the Contribution, effective on the date of the Transfer of Contribution Copyright, -where the INTO-CPS Association grants the Contributors a non-exclusive, world-wide, transferable, free of charge, perpetual license, including sublicensing rights, to use, +The transfer is free of charge. If the Contributors or +the INTO-CPS Association so wish, +an optional Copyright transfer agreement can be signed +between the INTO-CPS Association and the Contributors. + +"Contribution License" means a license from the INTO-CPS +Association to the Contributors of the Contribution, +effective on the date of the Transfer of Contribution Copyright, +where the INTO-CPS Association grants the Contributors +a non-exclusive, world-wide, transferable, free of charge, +perpetual license, including sublicensing rights, to use, have used, modify, have modified, reproduce and or have reproduced the contributed material, for business and other purposes, including but not limited to evaluation, development, testing, integration and merging with @@ -166,18 +196,19 @@ the INTO-CPS tool chain. "The Program" means the Contributions distributed in accordance with ICAPL. -"The INTO-CPS tool chain" means the Contributions distributed in accordance with ICAPL. +"The INTO-CPS tool chain" means the Contributions +distributed in accordance with ICAPL. "Recipient" means anyone who receives the INTO-CPS tool chain under ICAPL, including all Contributors. "Licensed Third Party Distributor" means a reseller/distributor having signed -a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS -Association Bylaws, with a Gold Level organizational member which is not an -Affiliate of the reseller/distributor, for distributing a product containing -part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall -only be allowed further redistribution to other resellers if the Gold Level -member is granting such a right to it in the redistribution/resale agreement +a redistribution/resale agreement in accordance with ICAPL and the INTO-CPS +Association Bylaws, with a Gold Level organizational member which is not an +Affiliate of the reseller/distributor, for distributing a product containing +part(s) of the INTO-CPS tool suite. The Licensed Third Party Distributor shall +only be allowed further redistribution to other resellers if the Gold Level +member is granting such a right to it in the redistribution/resale agreement between the Gold Level member and the Licensed Third Party Distributor. "Affiliate" shall mean any legal entity, directly or indirectly, through one @@ -197,7 +228,8 @@ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the -appropriateness of using and distributing the INTO-CPS tool suite and assumes all risks +appropriateness of using and distributing the +INTO-CPS tool suite and assumes all risks associated with its exercise of rights under ICAPL , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability @@ -211,16 +243,17 @@ SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL -SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE INTO-CPS TOOL +SUITE OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. A Contributor licensing the INTO-CPS tool suite under ICA-Internal-EPL or -ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite +ICA-External-EPL may choose to distribute (parts of) the INTO-CPS tool suite in object code form under its own license agreement, provided that: a) it complies with the terms and conditions of ICAPL; or for the case of -redistribution of the INTO-CPS tool suite together with proprietary code it is a dual +redistribution of the INTO-CPS tool suite together +with proprietary code it is a dual license where the INTO-CPS tool suite parts are distributed under ICAPL compatible conditions and the proprietary code is distributed under proprietary license conditions; and @@ -235,8 +268,10 @@ damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) states that any provisions which differ from ICAPL are offered by that Contributor alone and not by any other party; and - iv) states from where the source code for the INTO-CPS tool suite is available, and -informs licensees how to obtain it in a reasonable manner on or through a + iv) states from where the source code for the INTO-CPS +tool suite is available, and +informs licensees how to obtain it in a +reasonable manner on or through a medium customarily used for software exchange. When the INTO-CPS tool suite is made available in source code form: @@ -258,9 +293,11 @@ This Agreement is governed by the laws of Denmark. The place of jurisdiction for all disagreements related to this Agreement, is Aarhus, Denmark. The EPL 1.0 license definition has been obtained from: -http://www.eclipse.org/legal/epl-v10.html. It is also reproduced in the INTO-CPS distribution. +http://www.eclipse.org/legal/epl-v10.html. +It is also reproduced in the INTO-CPS distribution. The GPL Version 3 license definition has been obtained from -http://www.gnu.org/copyleft/gpl.html. It is also reproduced in the INTO-CPS distribution. +http://www.gnu.org/copyleft/gpl.html. +It is also reproduced in the INTO-CPS distribution. --- End of Definition of INTO-CPS Association Public License --- diff --git a/servers/lib/README.md b/servers/lib/README.md index 5080e8b94..74e8c1f1a 100644 --- a/servers/lib/README.md +++ b/servers/lib/README.md @@ -27,10 +27,11 @@ to get a sample file system structure for the lib microservice. The microservices uses `.env` environment files to receive configuration. -In order to create this environment, you need to create a `.env` file, wherein you create the following environment variables, +In order to create this environment, you need to create a `.env` file, +wherein you create the following environment variables, and insert with the correct-information relevant for your setup: -``` +```env PORT='4001' MODE='local' or 'gitlab' LOCAL_PATH ='/Users//DTaaS/files' @@ -46,7 +47,8 @@ The `TOKEN` should be set to your GitLab Group access API token. For more information on how to create and use your access token, [gitlab page](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html). -Once you've generated a token, copy it and replace the value of `TOKEN` with your token for the gitlab group, can be found. +Once you've generated a token, copy it and replace +the value of `TOKEN` with your token for the gitlab group, can be found. ## User Commands @@ -246,7 +248,6 @@ POST /lib HTTP/1.1 Host: localhost:4001 Content-Type: application/json Content-Length: 388 - { "query":"query {\n listDirectory(path: \"user1\") {\n repository {\n tree {\n blobs {\n edges {\n node {\n name\n type\n }\n }\n }\n trees {\n edges {\n node {\n name\n type\n }\n }\n }\n }\n }\n }\n}" } @@ -262,7 +263,6 @@ Content-Length: 306 Content-Type: application/json; charset=utf-8 Date: Tue, 26 Sep 2023 20:26:49 GMT X-Powered-By: Express - {"data":{"listDirectory":{"repository":{"tree":{"blobs":{"edges":[]},"trees":{"edges":[{"node":{"name":"data","type":"tree"}},{"node":{"name":"digital twins","type":"tree"}},{"node":{"name":"functions","type":"tree"}},{"node":{"name":"models","type":"tree"}},{"node":{"name":"tools","type":"tree"}}]}}}}}} ``` @@ -278,7 +278,6 @@ POST /lib HTTP/1.1 Host: localhost:4001 Content-Type: application/json Content-Length: 217 - { "query":"query {\n readFile(path: \"user2/data/welcome.txt\") {\n repository {\n blobs {\n nodes {\n name\n rawBlob\n rawTextBlob\n }\n }\n }\n }\n}" } @@ -292,6 +291,5 @@ Content-Length: 134 Content-Type: application/json; charset=utf-8 Date: Wed, 27 Sep 2023 09:17:18 GMT X-Powered-By: Express - {"data":{"readFile":{"repository":{"blobs":{"nodes":[{"name":"welcome.txt","rawBlob":"hello world","rawTextBlob":"hello world"}]}}}}} ``` diff --git a/servers/lib/test/README.md b/servers/lib/test/README.md index 06f3dacec..2f08acb61 100644 --- a/servers/lib/test/README.md +++ b/servers/lib/test/README.md @@ -2,9 +2,11 @@ Inorder to test the lib-MS, a specific file structure must be configured. -Since the tests are tested across two different modes, 'local' or 'gitlab', a homogenous file structure is required. +Since the tests are tested across two different modes, +'local' or 'gitlab', a homogenous file structure is required. -This file structure must be within 'files' aswell as within your working gitlab repository, as depicted below... +This file structure must be within 'files' aswell as within +your working gitlab repository, as depicted below... local file system: diff --git a/servers/lib/test/data/user2/tools/README.md b/servers/lib/test/data/user2/tools/README.md index 19a2e4aa3..a2a768c66 100644 --- a/servers/lib/test/data/user2/tools/README.md +++ b/servers/lib/test/data/user2/tools/README.md @@ -1 +1,3 @@ +# Tools + content123 diff --git a/ssl/README.md b/ssl/README.md index c4de3157f..2a1278bab 100644 --- a/ssl/README.md +++ b/ssl/README.md @@ -1,6 +1,8 @@ # Generate SSL Certificates for DTaaS application -Set the required passwords for private certificates in the **password** file. The first line will be used for the input password and the next line for the output password. +Set the required passwords for private certificates +in the **password** file. The first line will be used +for the input password and the next line for the output password. ## Using the shell script @@ -22,19 +24,17 @@ to **servers/gateway/certs** directory. 1) Take private/client.key.p12 certificate for the next steps 1) open firefox browser in regular, non-private mode. 1) open preferences (about:preferences) -1) search for "certificates" --> Certificate Manager --> +1) search for "certificates" --> Certificate Manager --> 1) Authorities --> import ca.cert.pem and checkmark Trust this CA to identify websites Trust this CA to identify email users - 1) Your Certificates --> Import --> Add PKCS12 format client certificate (client.key.p12) The password for this certificate is "dtaas" - - It's important to add the certificates inthe same order. Otherwise, certificate errors are shown. - -1) Setting default client SSL certificate for mTLS - a) Open an empty tab and type `about:config` - b) Accept the risk and continue + It's important to add the certificates inthe same order. + Otherwise, certificate errors are shown. +1) Setting default client SSL certificate for mTLS + a) Open an empty tab and type `about:config` + b) Accept the risk and continue c) In the search bar, type: `security.default_personal_cert = Select Automatically` ### References