dtaas 0.2.0

DTaaS CLI

DTaaS Command Line Interface

This is a command line tool for the INTO-CPS-Association Digital Twins as a Service.

Prerequisite

Please visit and download the DTaaS Software.

The DTaaS application with base users and essential containers should be up and running before using the CLI.

Installation

Simply install using:

We recommend installing this in a virutal environment.

Steps to install:

• Change the working folder:

cd <DTaaS-directory>/cli

• We recommend installing this in a virtual environment. Create and activate a virtual environment.

• To install, simply:

pip install dtaas

Usage

Setup

The base DTaaS system should be up and running before adding/deleting users with the CLI.

Additionally, Setup the dtaas.toml file in the cli directory:

• Set common.server-dns to domain name of your server. If you want to bring up the server locally, please set this to "localhost".

• Set the path to the full system path of the DTaaS directory.

[common]
# absolute path to the DTaaS application directory
server-dns = "localhost"
# Specify the directory of DTaaS installation
# Linux example
path = "/home/Desktop/DTaaS"
# Windows example
#path = "C:\\Users\\XXX\\DTaaS"
# Note: You have to either use / or \\ when specifying path, else you would get 
# "Error while getting toml file: dtaas.toml, Invalid unicode value"

Select Template

The cli uses YAML templates provided in this directory to create new user workspaces. The templates are:

1. user.local.yml: localhost installation
2. User.server.yml: multi-user web application application over HTTP
3. user.server.secure.yml: multi-user web application application over HTTPS

Please note that the cli is not capable of detecting the difference between HTTP and HTTPS modes of web application. Thus if you are serving web application over HTTPS, please do one extra step.

cp user.server.secure.yml user.server.yml

This will change the user template from insecure to secure.

Add users

To add new users using the CLI, fill in the users.add list in dtaas.toml with the Gitlab instance usernames of the users to be added

[users]
# matching user info must present in this config file
add = ["username1","username2", "username3"]

Make sure you are in the cli directory.

Then simply:

dtaas admin user add

The command checks for the existence of files/<username> directory. If it does not exist, a new directory with correct file structure is created. The directory, if it exists, must be owned by the user executing dtaas command on the host operating system. If the files do not have the expected ownership rights, the command fails.

Caveats

This brings up the containers, without the AuthMS authentication.

• Currently the email fields for each user in dtaas.toml are not in use, and are not necessary to fill in. These emails must be configured manually for each user in the deploy/docker/conf.server files and the traefik-forward-auth container must be restarted. This is done as follows:

• Go to the docker directory

cd <DTaaS>/deploy/docker

• Add three lines to the conf.server file

rule.onlyu3.action=auth
rule.onlyu3.rule=PathPrefix(`/user3`)
rule.onlyu3.whitelist = [e-mail]

• Run the command for these changes to take effect:

docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth

The new users are now added to the DTaaS instance, with authorization enabled.

Delete users

• To delete existing users, fill in the users.delete list in dtaas.toml with the Gitlab instance usernames of the users to be deleted.

[users]
# matching user info must present in this config file
delete = ["username1","username2", "username3"]

• Make sure you are in the cli directory.

Then simply:

dtaas admin user delete

• Remember to remove the rules for deleted users in conf.server.

Additional Points to Remember

• The user add CLI will add and start a container for a new user. It can also start a container for an existing user if that container was somehow stopped. It shows a Running status for existing user containers that are already up and running, it doesn't restart them.

• user add and user delete CLIs return an error if the add and delete lists in dtaas.toml are empty, respectively.

• '.' is a special character. Currently, usernames which have '.'s in them cannot be added properly through the CLI. This is an active issue that will be resolved in future releases.