Configuration of tools

Getting started

To add a tool to the Collaboration Manager, it must fulfill the following requirements:

The tool must run in a single Docker container (no sidecar containers).
The Docker container has to run with a non-root user.
The Docker image has to be deployed to a Docker registry, which is accessible from the Collaboration Manager server environment.
The tool must be exposed via RDP or HTTP/HTTPS.
If the tool is exposed via RDP, it must accept basic authentication. For HTTP-based tools, authentication is handled automatically via pre-authentication.
The container must expose a /metrics endpoint with an idletime_minutes gauge metric in the OpenMetrics format, which returns the time in minutes since the last user interaction. The metric is used to determine if the session is idle and can be terminated.
If you want to capture session logs and make them accessible via Grafana Loki, they have to be written to disk (stdout/stderr are not persisted).

YAML Configuration

For a full documentation of all available options, refer to the API documentation.

Resources

For each tool, you can define the resources which sessions of the tool can use. This is a significant option because it impacts cost and performance.

An example configuration looks like this:

resources:
  cpu:
    requests: 0.4
    limits: 2
  memory:
    requests: 1.6Gi
    limits: 6Gi

The values are Kubernetes resource requests and limits. More information is available in the API documentation and the Kubernetes documentation.

Environment variables

Predefined environment variables

General variables

We set the following environment variables for each session container. The variables can be used by the tool:

Environment Variable	Example value	Description
`CAPELLACOLLAB_SESSION_TOKEN`	`KYYfLPiRVFijT7ZPhVx6DO0oPQcrfEInDetonD0nIKGnQmC9pWAfHq9xxKiYqUdj`	Token, which the tool has to use to authenticate the user.
`CAPELLACOLLAB_SESSION_ID`	`tctszsirxuoohabwnhyhmzjdh`	Unique Session ID of the session, can be used for API request to the Collaboration Manager API.
`CAPELLACOLLAB_SESSION_CONNECTION_METHOD_TYPE`	`guacamole`	`http` or `guacamole`, depending on the requested connection method.
`CAPELLACOLLAB_SESSION_REQUESTER_USERNAME`	`janedoe`	The username of the user who has requested the session.
`CAPELLACOLLAB_SESSION_CONTAINER_PORT`	`8080`	The port that the application has to serve on. HTTP port if connection method is `http` and RDP port if the connection method is `guacamole`.
`CAPELLACOLLAB_SESSION_PROVISIONING`	`[ { "url": "https://github.com/DSD-DBS/coffee-machine", "revision": "main", "depth": 1, "entrypoint": "coffee-machine-demo.aird", "nature": "model", "path": "/models/coffee-machine/coffee-machine" } ]`	A list of dictionaries containing information about the models that were provisioned by the Collaboration Manager in the JSON format. Each list item contains the following attributes: - `url`: The URL of the Git repository. - `revision`: The revision of the Git repository. - `depth`: The depth that was used while cloning the Git repository. - `entrypoint`: The entrypoint of the Git repository. - `nature`: The nature of the model in the Collaboration Manager. - `path`: The path to the model in the session.
`CAPELLACOLLAB_SESSIONS_SCHEME`	`https`	HTTP scheme, can be `http` or `https`
`CAPELLACOLLAB_SESSIONS_HOST`	`sessions.example.com`	The hostname of the sessions environment.
`CAPELLACOLLAB_SESSIONS_PORT`	`443`	The port of the sessions environment. Can be different to the port in `CAPELLACOLLAB_ORIGIN_HOST` if the sessions run on a different port (e.g. in our local non-cluster development environment).
`CAPELLACOLLAB_SESSIONS_BASE_PATH`	`/session/2037430`	The base path that the session application has to serve requests on. Only available if `CAPELLACOLLAB_SESSION_CONNECTION_METHOD_TYPE` is `http`.
`CAPELLACOLLAB_ORIGIN_BASE_URL`	`https://frontend.example.com:443`	The origin host of the Collaboration Manager. The tool has to set the `Content-Security-Policy` header to `frame-ancestors self {CAPELLACOLLAB_ORIGIN_HOST}`. Otherwise, the session viewer can't be used with the tool!

TeamForCapella variables

In addition, the following variables are mounted if the TeamForCapella integration is enabled for the tool and the session type is persistent.

For a explanation of those variables, refer to the Capella Docker images documentation.

Environment Variable	Example value	Description
`T4C_LICENCE_SECRET`	`1234123412341252435234523452345123423`	License configuration for the TeamForCapella server.
`T4C_JSON`	`[ { "repository": "repoCapella", "host": "localhost", "port": 2036, "instance": "default", "protocol": "ssl" } ]`	JSON containing all repositories the user has access to. The format is described in the Capella Docker images documentation.
`T4C_USERNAME`	`admin`	Username of the session requester on the TeamForCapella server. Can be used to authenticate against the repositories the user has access to.
`T4C_PASSWORD`	`adfaw34rfqadsc`	Session token to authenticate against the TeamForCapella server. The token is auto-created and valid for all TeamForCapella repositories the user has access to.

Definition of custom environment variables

If you don't have the possibility to set environment variables in your tool, you can also define custom variables. You can also derive variables from pre-defined values.

A variable is defined in the tool configuration:

environment:
  MY_TOOL_USERNAME_WITH_PREFIX: 'test_{CAPELLACOLLAB_SESSION_REQUESTER_USERNAME}'

In this example, we map the MY_TOOL_USERNAME variable to the MY_TOOL_USERNAME_WITH_PREFIX environment variable and add the test_ prefix. You can use f-string formatting with all pre-defined environment variables, but also define static variables.

Connection methods

Each tool can support different connection methods. A connection methods defines how the user connects to a session of the tool. You can define up to 10 connections methods for each tool. The user can select the preferred connection method in the session request form.

Guacamole

To connect to RDP based tools, you can use our integration of Apache Guacamole. The Collaboration Manager will interact with the Guacamole API to create users and connections.

Guacamole will try to authenticate with the following credentials against the RDP server. The RDP server has to run in the container and has to accept those credentials:

username="techuser"
password=CAPELLACOLLAB_SESSION_TOKEN

The configuration looks like:

connection:
  methods:
    - identifier: <unique-identifier>
      type: guacamole
      name: Classic
      description: ''
      ports:
        metrics: 9118
        rdp: 3389
      environment:
        ENVIRONMENT_VARIABLE: test

HTTP(S)

You can use any web-based tool with the HTTP(S) connection method. The configuration looks like:

connection:
  methods:
    - identifier: <unique-identifier>
      type: http
      name: HTTP
      description: ''
      ports:
        metrics: 9118
        http: 10000
      environment:
        ENVIRONMENT_VARIABLE: test
      redirect_url: '{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}'
      cookies:
        token: '{CAPELLACOLLAB_SESSION_TOKEN}'

Authentication

Since version 3.1.0 of the Collaboration Manager, it is no longer necessary for the tool itself to handle the authentication. Instead, the Collaboration Manager automatically authenticates all users via pre-authentication with session tokens.

Configuration examples

To help you configuring your tools, we provide some examples for the tools, which we provide as part of our Capella Docker images repository

Capella/Papyrus/EclipseJupyter

name: Eclipse # (1)
integrations:
  t4c: true # (2)
  pure_variants: false # (3)
  jupyter: false
config:
  resources:
    cpu:
      requests: 0.4
      limits: 2
    memory:
      requests: 1.6Gi
      limits: 6Gi
  environment:
    RMT_PASSWORD: "{CAPELLACOLLAB_SESSION_TOKEN}"
    ECLIPSE_PROJECTS_TO_LOAD: "{CAPELLACOLLAB_SESSION_PROVISIONING}"
  connection:
    methods:
      - id: guacamole
        type: guacamole
        name: Classic (Guacamole)
        description: Old connection method using Guacamole. If
          it has worked fine previously, keep using it.
          In case of issues, try the Xpra connection
          method.
        ports:
          metrics: 9118
          rdp: 3389
        environment:
          CONNECTION_METHOD: xrdp
      - id: xpra
        type: http
        name: Experimental (Xpra)
        description: Experimental connection method using Xpra.
          It's intended for those users who have issues
          with the Guacamole connection method.
        ports:
          metrics: 9118
          http: 10000
        environment:
          XPRA_SUBPATH: "{CAPELLACOLLAB_SESSIONS_BASE_PATH}"
          CONNECTION_METHOD: xpra
          XPRA_CSP_ORIGIN_HOST: "{CAPELLACOLLAB_ORIGIN_BASE_URL}"
        redirect_url: "{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}/?floating_menu=0&sharing=1&path={CAPELLACOLLAB_SESSIONS_BASE_PATH}/"
        cookies:
          token: "{CAPELLACOLLAB_SESSION_TOKEN}"
  monitoring:
    prometheus:
      path: /prometheus
  provisioning:
    directory: /models
    max_number_of_models: null
  persistent_workspaces:
    mounting_enabled: true

Use a clear and short name for the tool, e.g. Capella, Papyrus or Eclipse.
Activate if TeamForCapella support is needed. Set it to false for Papyrus and Eclipse.
For pure::variants support, set the value to true.

name: Jupyter
integrations:
  t4c: false
  pure_variants: false
  jupyter: true
config:
  resources:
    cpu:
      requests: 1
      limits: 2
    memory:
      requests: 500Mi
      limits: 3Gi
  environment:
    JUPYTER_PORT: "8888"
    JUPYTER_TOKEN: "{CAPELLACOLLAB_SESSION_TOKEN}"
    CSP_ORIGIN_HOST: "{CAPELLACOLLAB_ORIGIN_BASE_URL}"
    JUPYTER_BASE_URL: "{CAPELLACOLLAB_SESSIONS_BASE_PATH}"
    JUPYTER_ADDITIONAL_DEPENDENCIES: ""
  connection:
    methods:
      - id: jupyter
        type: http
        name: Direct Jupyter connection (Browser)
        description: The only available connection method for
          Jupyter.
        ports:
          metrics: 9118
          http: 8888
        environment: {}
        redirect_url: "{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}/lab?token={CAPELLACOLLAB_SESSION_TOKEN}"
        cookies: {}
        sharing:
          enabled: True
  monitoring:
    prometheus:
      path: /prometheus
  provisioning:
    directory: /models
    max_number_of_models: null
  persistent_workspaces:
    mounting_enabled: true