dtaas 0.4.0

DTaaS CLI

DTaaS Command Line Interface

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

📋 Prerequisite

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

📦 Installation

Installation in a virtual environment is recommended.

Steps to install:

• Change the working folder:

cd <DTaaS-directory>/cli

• Create and activate a virtual environment.

• Install the package:

pip install dtaas

📖 Usage

Generate Project Files

Before configuring the CLI, generate the required project files in your working directory:

dtaas generate-project

By default, this creates files in the current directory and skips any that already exist. You can customize this behaviour with the following options:

# Generate files in a specific directory
dtaas generate-project --output-dir /path/to/target/dir

# Overwrite existing files
dtaas generate-project --force

# Combine options
dtaas generate-project --output-dir /path/to/target/dir --force

Options:

• --output-dir (default: .): Target directory for generated files. The directory must already exist.
• --force: Overwrite existing files. Without this flag, existing files are left untouched and a message is printed.

This creates three configuration files and the workspace directory structure:

Item	Purpose
dtaas.toml	Main CLI configuration (server DNS, paths, resources, users)
users.server.yml	Docker Compose user-workspace template for HTTP deployments
users.server.secure.yml	Docker Compose user-workspace template for
HTTPS/TLS deployments
files/template/	Template directory for user workspace initialization

The files/template/ directory is created if it does not exist.

Important: Verify Docker Image Tag

The generated users.server.yml and users.server.secure.yml files contain a pinned Docker image tag for the workspace container (e.g., intocps/workspace:main-967bc10). This tag is baked into the templates at generation time and may become stale as the project evolves.

You should verify and update the Docker image tag in these templates to use a current, stable version before deploying user workspaces. Check the available tags in the INTO-CPS workspace repository or your Docker registry to ensure you are using an up-to-date image version.

Configure

The CLI uses dtaas.toml as configuration file. A sample configuration file is given here.

# This is the config for DTaaS CLI

name = "Digital Twin as a Service (DTaaS)"
version = "0.2.2"
owner = "The INTO-CPS-Association"
git-repo = "https://github.com/into-cps-association/DTaaS.git"

[common]
# Server hostname either localhost or a valid hostname, ex: intocps.org
# TODO : Update, we are now reusing hostname for this
server-dns = "localhost"
# absolute path to the DTaaS application directory
# Specify the directory of DTaaS installation
# Linux example
path = "/Users/username/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"

[common.security]
# Enable HTTPS/TLS for secure server deployment
# Set the tls flag to false to use the insecure user.server.yml, it is True by default
# so the 'user.server.secure.yml' will be used
tls = true

[common.resources]
# Default resource limits applied when creating user workspace containers.
# Keys:
# - cpus: integer count of virtual CPUs to allocate to the container
# - mem_limit: memory limit string accepted by Docker (e.g. "4G", "512M")
# - pids_limit: maximum number of processes the container may create
# - shm_size: size for /dev/shm (shared memory), e.g. "512m"
#
# Adjust these values to match your host capacity and tenancy policy.
cpus = 4
mem_limit = "4G"
pids_limit = 4960
shm_size = "512m"

# Example: Increase memory and lower CPU for heavier-memory workloads
# cpus = 2
# mem_limit = "8G"


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

Notes

• Edits to dtaas.toml affect new user containers created after the change.
• To apply updated limits to existing containers, recreate or restart the user container(s) (for example by removing and re-adding the user workspace via the CLI or by restarting the container in Docker Compose).
• Use units (M, G) for memory and shared memory values.

Generate Deployment Project

To generate the full project structure for a specific deployment scenario without downloading separate zip packages:

dtaas generate-deployment --type <name>

Available types:

--type	Deployment scenario	Support level
localhost	Single-machine Docker deployment	dev/demo only
insecure-server	Multi-user HTTP server deployment	insecure/demo only
secure-server	Multi-user HTTPS/TLS server deployment	production-supported
secure-server-gitlab	HTTPS/TLS server with integrated GitLab	production-supported
workspace-localhost	Workspace service with Dex on localhost	dev/demo only
workspace-secure-server	Workspace service with Keycloak in production	production-supported

[!WARNING] Templates labelled dev/demo only or insecure/demo only run over plain HTTP and use default or static credentials. They are not safe for internet-facing or shared deployments. Use a production-supported type for any environment reachable from outside your local machine.

Production-supported types still require manual hardening steps documented inside each generated project (see the README.md and CONFIGURATION.md shipped with the template).

Options:

• --type (required): Deployment scenario to generate.
• --output-dir (default: .): Target directory for generated files. The directory must already exist.
• --force: Overwrite existing files. Without this flag, existing files are left untouched and a message is printed.

Examples:

# Generate a localhost deployment in the current directory
dtaas generate-deployment --type localhost

# Generate a secure-server deployment in a specific directory
dtaas generate-deployment --type secure-server --output-dir /path/to/project

# Regenerate, overwriting any existing files
dtaas generate-deployment --type insecure-server --output-dir /path/to/project --force

Each type copies the relevant docker-compose.yml, configuration examples, and supporting files into the target directory, ready to be customised.

📁 Select Template

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

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

➕ 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"]

Ensure the working directory is cli.

Then run:

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"]

• Ensure the working directory is cli.

Then run:

dtaas admin user delete

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

📌 Additional Points

• 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.