Skip to content

Install

DTaaS logo

🎉 Thank you for downloading Digital Twin as a Service.

This README provides a quick-start installation guide. For detailed configuration reference, see config.md.

[!IMPORTANT] The hostname intocps.org is used for illustration throughout this guide. Replace it with the actual server hostname of the installation.

🌐 Overview

This package installs the DTaaS as a multi-user web application with an integrated GitLab CE instance. GitLab serves as both the OAuth 2.0 authorisation provider and the DevOps backend for digital twin projects.

DTaaS on Server

The docker-compose.yml starts the following services:

Service Purpose
traefik Reverse proxy with TLS termination
client DTaaS React frontend
user1 / user2 JupyterLab user workspaces
libms Library management microservice
traefik-forward-auth OAuth 2.0 authorisation middleware
gitlab Integrated GitLab CE (OAuth 2.0 provider)

📋 Prerequisites

Requirement Details
Docker Engine v28 or later with Compose plugin
Domain name A domain name (e.g. intocps.org) or IP address
TLS certificate fullchain.pem and privkey.pem for the domain. Obtain via certbot or a certificate provider

🚀 Quick Start

1. Create Configuration Files

1
2
3
cp config/.env.example       config/.env
cp config/conf.server.example config/conf.server
cp config/client.js.example     config/client.js

Edit config/.env — set SERVER_DNS, USERNAME1, USERNAME2. Leave the OAUTH_* variables as placeholders for now; they will be filled after the GitLab instance is running (see step 5).

See config.md for a complete reference of every variable.

2. Create User Workspace Directories

1
2
3
cp -R files/template files/<USERNAME1>
cp -R files/template files/<USERNAME2>
sudo chown -R 1000:100 files/*

3. Add TLS Certificates

1
2
cp /path/to/fullchain.pem certs/fullchain.pem
cp /path/to/privkey.pem   certs/privkey.pem

Traefik falls back to self-signed certificates if these files are absent or invalid.

4. Start Services

1
docker compose --env-file config/.env up -d

Wait a few minutes for GitLab to become healthy:

1
watch docker ps

5. Configure GitLab 🦊

Once the GitLab container shows as healthy:

  1. Log in to https://intocps.org/gitlab as root. The initial password is inside config/gitlab/initial_root_password.

[!WARNING] This file is deleted 24 hours after the first start. Save the password immediately.

  1. Create user accounts (see GitLab docs). The usernames must match USERNAME1/USERNAME2 in config/.env.

  2. Register two OAuth 2.0 applications in GitLab (Admin Area → Applications):

  3. DTaaS Client Authorization — for the React SPA frontend. See client auth docs.

  4. DTaaS Server Authorization — for Traefik forward-auth backend. See server auth docs.

  5. Update configuration files (config/.env and config/client.js) with the generated OAuth 2.0 tokens:

  6. Set REACT_APP_CLIENT_ID and REACT_APP_AUTH_AUTHORITY in config/client.js.

  7. Set OAUTH_URL, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET in config/.env.

  8. Update user permissions in config/conf.server.

  9. Reload the services:

1
docker compose --env-file config/.env up -d --force-recreate client traefik-forward-auth

6. Verify ✅

URL Expected result
https://intocps.org DTaaS web interface (redirects to GitLab sign-in)
https://intocps.org/gitlab Integrated GitLab instance
https://intocps.org/user1 User 1 workspace (after sign-in)
https://intocps.org/user2 User 2 workspace (after sign-in)

🛑 Stop

1
docker compose --env-file config/.env down

📁 Directory Layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
.
├── certs/                 # TLS certificates (fullchain.pem, privkey.pem)
├── config/
│   ├── .env               # Docker compose environment variables
│   ├── conf.server        # Traefik forward-auth authorization rules
│   ├── client.js             # DTaaS React client configuration
│   ├── gitlab/            # GitLab config (mounted as /etc/gitlab)
│   └── tls.yml            # Traefik TLS provider configuration
├── data/                  # GitLab persistent data (/var/opt/gitlab)
├── files/
│   ├── common/            # Shared files across all workspaces
|  \- template/           # sample user workspace files
├── logs/                  # GitLab logs (/var/log/gitlab)
├── docker-compose.yml     # Service definitions
├── CONFIG.md              # Detailed configuration reference
└── README.md              # This file — quick-start guide

:framed_picture: References

Image sources: Traefik logo, gitlab