Installation

Prerequisites

ubTrace is distributed as Docker containers. You need to have Docker and Docker Compose installed on your system. If you do not have Docker, follow the official Get Docker instructions.

Hint

The used setup has all features activated by default. Some feature (like the Chatbot) need some additional config parameters like API keys to work. As alternative, these features can be deactivated by Configuration.

Quickstart

  1. Download the Compose File

    Download the provided docker-compose.yml file. This file configures all required services for you.

    Content of docker-compose.yml
    ###############################################################################
# ubTrace Production Setup via docker compose
# -------------------------------------------
# For details please read: https://ubtrace.useblocks.com/installation.html
# Run it via: docker compose up
#
# Support via support@useblocks.com
###############################################################################

services:
################################
# UBTRACE SERVER
################################
  ubtrace:
    volumes:
      - ubtrace-data:/home/appuser/app/docs/ubtrace/
    image: ghcr.io/useblocks/ubtrace:v0.6.0
    depends_on:
      oidc:
        condition: service_healthy
    ports:
      - "7130:7130"
    working_dir: /
    environment:
      MESSAGE: 🌍 Starting ubTrace on http://localhost:7130
      PUBLIC_VIS_TREE_HOST: http://localhost:7140
      UBTRACE_SERVER_SIDEBAR_APPS_CONFIG: '{"traceability_tree": "http://localhost:7140"}'
      UBTRACE_SERVER_VIS_TREE_INTERNAL_HOST: http://vis-tree:7140
      UBTRACE_SERVER_AUTH_ISSUER_URL: http://oidc:7180
      PUBLIC_AUTH_ISSUER_URL: http://localhost:7180
      UBTRACE_SERVER_AUTH_DISCOVERY_URL: http://oidc:7180/.well-known/openid-configuration
      OPENROUTER_APIKEY: ${OPENROUTER_APIKEY}
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:7130/health"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s

################################
# VIS-TREE
################################
  vis-tree:
    volumes:
      - ubtrace-data:/home/appuser/app/docs/ubtrace/
    image: ghcr.io/useblocks/vis-tree:v0.6.0
    ports:
      - "7140:7140"
    depends_on:
      oidc:
        condition: service_healthy
      ubtrace:
        condition: service_healthy
    working_dir: /app
    environment:
      MESSAGE: 🌍 Starting Vis-Tree on http://localhost:7140
      ISSUER: http://oidc:7180
      CLIENT_ID: ubtrace-client
      JWKS_URL: http://oidc:7180/.well-known/jwks.json
      PUBLIC_AUTH_DISABLED: true
      CORS_ALLOWED_ORIGINS: http://localhost:7130, http://127.0.0.1:7130, http://0.0.0.0:7130
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:7140/health']
      interval: 10s
      timeout: 5s
      retries: 15
      start_period: 45s

################################
# OIDC Auth server
################################
  oidc:
    image: ghcr.io/useblocks/oidc:v0.6.0
    command: python -m oidc_local_server.app
    ports:
      - '7180:7180'
    working_dir: /app
    environment:
      LOCAL_OIDC_SERVER_PORT: 7180
      LOCAL_OIDC_CLIENT_ID: ubtrace-client
      CORS_ALLOWED_ORIGINS: http://localhost:7130, http://127.0.0.1:7130, http://0.0.0.0:7130
    healthcheck:
      test:
        [
          'CMD',
          'curl',
          '-f',
          'http://localhost:7180/.well-known/openid-configuration',
        ]
      interval: 8s
      timeout: 3s
      retries: 10
      start_period: 20s

  ################################
  # MCP Server
  ################################
  mcp-server:
    image: ghcr.io/useblocks/mcp-server:v0.6.0
    depends_on:
      ubtrace:
        condition: service_started
    ports:
      - '7160:7160'
    volumes:
      - ubtrace-data:/home/appuser/app/docs/ubtrace/
    working_dir: /app
    environment:
      DOCS_ROOT_PATH: '/home/appuser/app/docs/ubtrace'
      MESSAGE: 🧠 Starting MCP Server on http://localhost:7160
    restart: on-failure
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:7160/health']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s


################################
# Internal volumes
################################
volumes:
  ubtrace-data:

  2. Start ubTrace

    Start ubTrace and its services with: docker compose up

    By default, Docker Compose looks for a docker-compose.yml file in the current directory.

    If you use a different filename, start with: docker compose -f my-docker-compose.yml up

    The first run may take a few minutes as images are downloaded and initialized. Subsequent restarts are much faster (usually 1–2 seconds).

    Note: You need a working internet connection for the initial setup.

    Hint

    Docker will start three containers:

    • ubTrace: The main application

    • Vis-Tree: Analysis tool for data visualization and representation, used by ubTrace

    • OIDC: User identity server, used by ubTrace for user login. Can be replaced by any company identity provider to reuse company accounts (recommended for professional setups).

  3. Stop ubTrace

    To stop all services, run: docker compose down

    This will stop and remove all containers and their setup.

  4. Update to the Latest Version

    To check and download the latest version for ubTrace, trigger Docker to pull new images: docker compose pull

Access ubTrace

Open your browser and go to http://127.0.0.1:7130. You should see the ubTrace Welcome Page and can navigate to available projects.

A test account is automatically created for you: test-oidc-user@useblocks.com. A password is not needed.

Demo Data

ubTrace includes demo documentation projects so you can test features immediately.

Under the organization useblocks, the following projects and versions are available:

  • ubTrace (Version 1): The official ubTrace documentation. Does not contain any Sphinx-Needs objects.

  • Showcase (Versions 1, 2, 3, 4): A small showcase project with a limited number of Sphinx-Needs objects. Object data changes and is extended across different versions.

  • Sphinx-Needs-Demo (Version 1): The Sphinx-Needs-Demo documentation. Provides more than 100 Need objects.

Custom Data

You can add your own Sphinx projects to ubTrace.

  1. Build your Sphinx project using the ubTrace builder: make ubtrace

  2. Map your build output into the ubTrace container by updating your docker-compose.yml:

    ubtrace:
  volumes:
    # - ubtrace-data:/home/appuser/app/docs/ubtrace/  # Prior config
    - ./my_docs/_build/ubtrace/:/home/appuser/app/docs/ubtrace/

    Note: The syntax is LOCAL_PATH:SERVER_PATH.

    SERVER_PATH must be /home/appuser/app/docs/ubtrace.

    LOCAL_PATH can be any folder on your machine, but it must contain the structure generated by the ubTrace builder.

  3. Start ubTrace with docker compose up.

For more details, see Project Integration.

Mounting your own docs into ubTrace will replace the default documentation projects from the running instance, so that only your docs are available. To get them back, just switch back to the original mounting.