Configuration Reference

This page describes every configuration file in this package. For the quick-start installation guide, see install.md.

Important

This guide uses the hostname intocps.org as an example. Replace it with the hostname of your server.

config/.env - Docker Compose Environment

Source: config/.env.example

This file holds the environment variables that docker-compose.yml reads.

1	`cp config/.env.example config/.env`

Server Settings

Variable	Example	Description
`SERVER_DNS`	`intocps.org`	Domain name or IP address of the server. Do not include `https://`.
`USERNAME1`	`user1`	Path prefix and workspace name for the first user
`USERNAME2`	`user2`	Path prefix and workspace name for the second user
`COMPOSE_PROJECT_NAME`	`dtaas`	Docker Compose project name (rarely needs changing)

OAuth 2.0 Settings

Fill these in after the GitLab instance is running and the OAuth 2.0 applications exist (see OAuth 2.0 Application Setup).

Variable	Example	Description
`OAUTH_URL`	`https://intocps.org/gitlab`	GitLab instance URL used for browser-side authorisation redirects. No trailing slash.
`OAUTH_CLIENT_ID`	(from GitLab)	Application ID from the DTaaS Server Authorization OAuth 2.0 application
`OAUTH_CLIENT_SECRET`	(from GitLab)	Secret from the DTaaS Server Authorization OAuth 2.0 application
`OAUTH_SECRET`	(random string)	Encryption key for OAuth session cookies. Generate with: `openssl rand -base64 32`

How Variables Map to Services

Variable	Used by
`SERVER_DNS`	client, logger-ms, user1, user2, libms, traefik-forward-auth, gitlab
`USERNAME1` / `USERNAME2`	user1, user2 (routing and workspace volumes)
`OAUTH_URL`	traefik-forward-auth (browser redirect URL)
`OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET`	traefik-forward-auth
`OAUTH_SECRET`	traefik-forward-auth

traefik-forward-auth reaches the token and user endpoints over the internal Docker network (http://gitlab/gitlab/...), so only the authorisation redirect uses OAUTH_URL.

config/client.js - DTaaS Web Client

Source: config/client.js.example

This JavaScript file is mounted into the React client container and configures the DTaaS web application at runtime.

1	`cp config/client.js.example config/client.js`

Variable Reference

Variable	Example	Description
`REACT_APP_ENVIRONMENT`	`prod`	Environment name. Use `prod` for production.
`REACT_APP_URL`	`https://intocps.org`	Base URL of the DTaaS web application
`REACT_APP_URL_BASENAME`	`''`	Optional URL base path (leave empty for root hosting)
`REACT_APP_URL_DTLINK`	`/lab`	URL path for the Digital Twin workbench
`REACT_APP_URL_LIBLINK`	`''`	URL path for the Library
`REACT_APP_CLIENT_ID`	(from GitLab)	Application ID from the DTaaS Client Authorization OAuth 2.0 application
`REACT_APP_AUTH_AUTHORITY`	`https://intocps.org/gitlab`	URL of the GitLab instance (OAuth 2.0 issuer)
`REACT_APP_REDIRECT_URI`	`https://intocps.org/Library`	Where GitLab sends users after sign-in
`REACT_APP_LOGOUT_REDIRECT_URI`	`https://intocps.org/`	Where users land after sign-out
`REACT_APP_GITLAB_SCOPES`	`openid profile read_user read_repository api`	OAuth 2.0 scopes requested during sign-in
`LOGGER_URL`	`https://intocps.org/logger`	URL of the logger service

Example

if (typeof window !== 'undefined') {
  window.env = {
    REACT_APP_ENVIRONMENT: 'prod',
    REACT_APP_URL: 'https://intocps.org',
    REACT_APP_URL_BASENAME: '',
    REACT_APP_URL_DTLINK: '/lab',
    REACT_APP_URL_LIBLINK: '',
    REACT_APP_CLIENT_ID: '<APPLICATION_ID>',
    REACT_APP_AUTH_AUTHORITY: 'https://intocps.org/gitlab',
    REACT_APP_REDIRECT_URI: 'https://intocps.org/Library',
    REACT_APP_LOGOUT_REDIRECT_URI: 'https://intocps.org/',
    REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
    LOGGER_URL: 'https://intocps.org/logger',
  };
};

config/conf.server - Traefik Forward-Auth Rules

Source: config/conf.server.example

This file defines per-path authorisation rules for traefik-forward-auth. Each rule restricts a URL path to specific GitLab email addresses.

1	`cp config/conf.server.example config/conf.server`

Format

1
2
3

rule.<NAME>.action=auth
rule.<NAME>.rule=PathPrefix(`/<path>`)
rule.<NAME>.whitelist=<email>

Default Rules

rule.libms.action=auth
rule.libms.rule=PathPrefix(`/lib`)

rule.onlyu1.action=auth
rule.onlyu1.rule=PathPrefix(`/user1`)
rule.onlyu1.whitelist=user1@emailservice.com

rule.onlyu2.action=auth
rule.onlyu2.rule=PathPrefix(`/user2`)
rule.onlyu2.whitelist=user2@emailservice.com

Replace user1, user2 and the email addresses with those of the actual GitLab accounts.

Important Rules

Warning

The usernames in config/.env (USERNAME1, USERNAME2) must match the PathPrefix values in config/conf.server. A mismatch causes routing or authorisation failures.

Scenario	Behaviour
Route in `config/.env` but missing from `config/conf.server`	Any signed-in user can access the route (default forward-auth behaviour)
Route in `config/conf.server` but missing from `config/.env`	Traefik returns 404 (route not served)
The `/lib` rule has no whitelist	Any signed-in user can access the library service

certs/ - TLS Certificates

Place the TLS certificate files here:

1
2
3

certs/
├── fullchain.pem   # Public certificate (or certificate chain)
└── privkey.pem     # Private key

The certificates must be valid for SERVER_DNS (e.g. intocps.org or *.intocps.org).

To obtain certificates with certbot:

# Using certbot (Let's Encrypt)
sudo certbot certonly --standalone -d intocps.org
sudo cp /etc/letsencrypt/live/intocps.org/fullchain.pem certs/
sudo cp /etc/letsencrypt/live/intocps.org/privkey.pem   certs/

If the certificate files are absent or invalid, Traefik uses self-signed certificates and browsers show a security warning.

files/ - User Workspace Directories

Each user workspace container mounts a directory from files/ as its /workspace volume. All workspaces share the files/common/ directory, which is mounted at /workspace/common in each container.

1
2
3

files/
├── common/    # Shared files (mounted to /workspace/common in each container)
└── template/  # template workspace files

Create a directory for each user:

cp -R files/template files/<USERNAME>
sudo chown -R 1000:100 files/*

UID 1000 and GID 100 match the default user inside the workspace container.

logs/logger/ - Logger Microservice Events

The logger microservice writes the captured events to logs/logger/workflow-logs.jsonl. Create the directory and give it to uid 1000, the user that runs the logger:

mkdir -p logs/logger
sudo chown -R 1000:1000 logs/logger

logs/ itself holds the GitLab logs, so change the owner of logs/logger only.

OAuth 2.0 Application Setup

Once the GitLab instance is running, register two OAuth 2.0 applications to connect DTaaS and Traefik forward-auth to the integrated GitLab.

DTaaS Client Authorization (React Frontend)

In GitLab, go to Admin Area → Applications (or the user's Edit Profile → Applications).
Create a new application:
Name: DTaaS Client Authorization
Redirect URI: https://intocps.org/Library
Confidential: unticked (public SPA client)
Scopes: openid, profile, read_user, read_repository, api
Save the Application ID.
Set REACT_APP_CLIENT_ID in config/client.js to this Application ID.
Set REACT_APP_AUTH_AUTHORITY in config/client.js to https://intocps.org/gitlab.

For details, see the client auth documentation.

DTaaS Server Authorization (Traefik Forward-Auth)

In GitLab, go to Admin Area → Applications.
Create a new application:
Name: DTaaS Server Authorization
Redirect URI: https://intocps.org/_oauth
Confidential: ticked
Scopes: read_user
Save the Application ID and Secret.
Set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET in config/.env.
Set OAUTH_URL in config/.env to https://intocps.org/gitlab.
Generate OAUTH_SECRET with openssl rand -base64 32 and set it in config/.env.

For details, see the server auth documentation.

Reload After Configuration

After putting the OAuth 2.0 credentials into the configuration files, reload the affected services:

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

Adding More Users

To add a third user:

Add a service to docker-compose.yml:

user3:
  image: intocps/workspace:main-56c6f68
  restart: unless-stopped
  environment:
    - MAIN_USER=${USERNAME3:-user3}
  volumes:
    - "./files/common:/workspace/common"
    - "./files/${USERNAME3:-user3}:/workspace"
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.u3.rule=Host(`${SERVER_DNS:-localhost}`) && PathPrefix(`/${USERNAME3:-user3}`)"
    - "traefik.http.routers.u3.tls=true"
    - "traefik.http.routers.u3.middlewares=traefik-forward-auth"
  networks:
    - users

Add to config/.env:

1	`USERNAME3=alice`

Create the workspace directory:

cp -R files/template files/alice
sudo chown -R 1000:100 files/alice

Add an authorisation rule to config/conf.server:

1
2
3

rule.onlyu3.action=auth
rule.onlyu3.rule=PathPrefix(`/alice`)
rule.onlyu3.whitelist=alice@emailservice.com

Create a GitLab account for alice in the integrated GitLab instance.
Restart:

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

Troubleshooting

GitLab Takes Too Long to Start

GitLab CE needs substantial resources, and the first startup can take 5 to 10 minutes. Follow progress with docker compose --env-file config/.env logs -f gitlab. Make sure the host has at least 4 GB of RAM available for GitLab.

Authentication Redirect Loop

Check that OAUTH_URL in config/.env matches the URL that the user's browser can reach (e.g. https://intocps.org/gitlab).
Check that REACT_APP_AUTH_AUTHORITY in config/client.js matches the same URL.
Clear the browser cookies for the domain.
Check the traefik-forward-auth logs: docker compose --env-file config/.env logs traefik-forward-auth

404 on User Workspace

Make sure USERNAME1/USERNAME2 in config/.env match the PathPrefix values in config/conf.server.
Make sure a matching service exists in docker-compose.yml.

GitLab "502 Bad Gateway"

GitLab is still initialising. Wait until docker ps shows the container as healthy.

Self-Signed Certificate Warning in Browser

The TLS certificate files in certs/ are missing or invalid. Replace them with valid certificates for the domain.