Skip to content

Platform Services

It is recommended to install certain third-party software for use by digital twins running inside the DTaaS software. These services can only be installed in secure (TLS) mode.

The following services can be installed:

  • Influx time-series database and dashboard service
  • Grafana visualization and dashboard service
  • RabbitMQ AMQP broker and its management interface The MQTT plugin of this broker has been enabled. So, it can also be used as MQTT broker.
  • MongoDB database server
  • ThingsBoard IoT device management and data visualization platform (with PostgreSQL backend)
  • GitLab OAuth2 identity provider and Git repository service

DTaaS Services CLI

A command-line tool for managing DTaaS platform services including MongoDB, InfluxDB, RabbitMQ, Grafana, ThingsBoard, and GitLab.

Features

  • Project Initialisation: Generate project structure with config and data directories
  • Automated Setup: One command setup of TLS certificates and permissions
  • Service Management: Start, stop, and check status of all services
  • User Management: Easy creation of user accounts in InfluxDB, RabbitMQ, MongoDB, PostgreSQL, ThingsBoard, and GitLab
  • Cross platform: Works on Linux, macOS, and Windows
  • Configuration-driven: Reads settings from config/services.env

Prerequisites

  • Python 3.10 or higher
  • Docker and Docker Compose
  • TLS certificates

Installation

Install the package inside a Python virtual environment:

1
pip install dtaas-services

This installs the dtaas-services command.

To verify the installation:

1
dtaas-services --help

Quick Start

  1. Navigate to the desired setup location and generate the project structure:
1
dtaas-services generate-project

This creates: * config is used for storing the service configuration * data is used by the services for storing data * certs is used for storing the TLS certificates needed by the services * compose.services.yml for main services * compose.thingsboard.yml for ThingsBoard and PostgreSQL

  1. Update config/services.env with the environment values:
  2. HOSTNAME: Public hostname of the DTaaS server (used for certificate paths)
  3. GITLAB_PORT: Port for the local GitLab instance (default: 8090)
  4. GITLAB_ROOT_NEW_PASSWORD: Strong password to set for the GitLab root admin
  5. TB_SYSADMIN_NEW_PASSWORD: New password for the ThingsBoard system admin
  6. Port numbers for each service
  7. TB_TENANT_ADMIN_PASSWORD: New password for the tenant admin
  8. SERVICES_UID: User ID for service file ownership

  9. SERVICES_GID: Group ID for service file ownership

  10. Update config/credentials.csv with user accounts (format: username,password,email)

Options:

  • --path Directory to generate project structure (default: current directory)

Example:

1
dtaas-services generate-project --path /path/to/project

Usage

Service Setup

After generating the project and configuring the settings:

1
dtaas-services setup

This command will:

  • Copy TLS certificates to the correct locations
  • Set up MongoDB certificates and permissions
  • Set up InfluxDB certificates and permissions
  • Set up RabbitMQ certificates and permissions
  • Set up PostgreSQL and ThingsBoard certificates and permissions

Ensure the clean command is run right after:

1
dtaas-services clean

Managing Services

Now services can be managed by simple commands such as start, stop, remove, restart, and status.

Example:

1
dtaas-services start

A specific service can be specified:

1
dtaas-services stop -s influxdb

Remove services and their volumes:

1
2
3
dtaas-services remove -v
# Specify
dtaas-services remove -v -s <service_name>

User Account Management

  1. Edit config/credentials.csv with user accounts (format: username,password,email)

  2. Add users to all supported services:

    1
    dtaas-services user add

    This creates user accounts in InfluxDB, RabbitMQ, MongoDB, PostgreSQL, ThingsBoard, and GitLab (each service is skipped gracefully if it is not running). For GitLab, a Personal Access Token is created for each new user and saved to config/gitlab_user_tokens.json.

  3. Add users to a specific service:

    1
    dtaas-services user add -s rabbitmq

ThingsBoard

It is recommended to install the third-party software ThingsBoard for use by digital twins running inside the DTaaS software. This service can only be installed in secure (TLS) mode.

The steps given above install two services:

  • ThingsBoard is an IoT device management and data visualization platform
  • PostgreSQL is a database server for ThingsBoard

ThingsBoard Installation

Warning: Running dtaas-services install -s thingsboard more than once will re-run the ThingsBoard schema migration against an already-populated PostgreSQL database, which can corrupt it. To reinstall from scratch, run dtaas-services clean -s "postgres,thingsboard" first to wipe all data before re-running the install command. Note: It is recommended to specify the service explicitly with -s <service> when installing. Ensure that the clean command has been run before the installation.

1
2
# It starts PostgreSQL if it is not running, and it checks its health.
dtaas-services install -s thingsboard

1
dtaas-services start -s thingsboard

1
2
3
# After installation, wait some time before adding users.
# This creates the tenant, tenant admin, and users.
dtaas-services user add -s thingsboard

Reset the ThingsBoard sysadmin and tenant admin passwords using values configured in config/services.env:

1
dtaas-services user reset-password -s thingsboard

This command:

  • Changes the sysadmin password from the default ("sysadmin") to TB_SYSADMIN_NEW_PASSWORD
  • Changes the tenant admin password from the default ("tenant") to TB_TENANT_ADMIN_PASSWORD

GitLab Installation

Prerequisites:

  • The GitLab container joins the dtaas-services Docker network (platform-services), which is created automatically when the other platform services are running. Start them first with dtaas-services start before installing GitLab.
  • Set REACT_APP_AUTH_AUTHORITY in the client config file to match the local GitLab authority URL used by your DTaaS deployment.

Note: The DTaaS client uses react-oidc-context, which forces redirects to use HTTPS. GitLab must therefore be served over HTTPS at https://<hostname>:<GITLAB_PORT>/gitlab

To install and configure the local GitLab instance:

1
dtaas-services install -s gitlab

GitLab takes 5 to 10 minutes to become healthy after the first start. The install command checks GitLab readiness and returns immediately:

  • If GitLab is healthy: the command runs post-install setup (password reset, PAT creation, OAuth app registration) and saves the access token to config/gitlab_tokens.json.
  • If GitLab is still starting: the command prints a status hint and exits. Check progress with dtaas-services status -s gitlab and re-run dtaas-services install -s gitlab once the status shows healthy.

Note: After a successful setup, config/gitlab_tokens.json is backed up to config/backup_gitlab_tokens.json and the root_password entry is removed from the live tokens file. If the GitLab installation becomes corrupted before the root password is changed, the initial password can be found in the backup file: config/backup_gitlab_tokens.json. If that file is also missing, re-install GitLab to generate a new initial password. Warning: config/password.env.current is managed automatically by the CLI and tracks the current service passwords. Do not edit or delete this file manually, as doing so may cause password reset commands to fail.

To complete the OAuth2 integration with DTaaS and set up GitLab Runner, follow the integration guide and the runner setup guides for either Linux or Windows.

Reset the GitLab root admin password using the value configured in config/services.env (GITLAB_ROOT_NEW_PASSWORD):

1
dtaas-services user reset-password -s gitlab

The command reads the new password to GITLAB_ROOT_NEW_PASSWORD and applies it via the GitLab API.

GitLab Post-Install Flow

The dtaas-services install -s gitlab command performs the following steps automatically:

  1. Starts the GitLab Docker container.
  2. Checks whether GitLab is healthy.
  3. Reads the auto-generated root password from the container (/etc/gitlab/initial_root_password).
  4. Creates an initial Personal Access Token and saves it to config/gitlab_tokens.json.
  5. Creates server and client OAuth application tokens.

Manual Compose Operations

After generating a services project, services may be operated manually with compose files:

  • compose.services.yml
  • compose.thingsboard.yml
  • compose.gitlab.yml

Start manually:

1
2
3
docker compose -f compose.services.yml --env-file config/services.env up -d
docker compose -f compose.thingsboard.yml --env-file config/services.env up -d
docker compose -f compose.gitlab.yml --env-file config/services.env up -d

Stop manually:

1
2
3
docker compose -f compose.services.yml --env-file config/services.env down
docker compose -f compose.thingsboard.yml --env-file config/services.env down
docker compose -f compose.gitlab.yml --env-file config/services.env down

Troubleshooting

Permission Issues (Linux/macOS)

1
sudo -E env PATH="$PATH" dtaas-services setup

Docker connectivity

1
docker ps

ThingsBoard connection error

After starting ThingsBoard and before adding users or changing passwords, allow some time for initialisation before adding users.