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.

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/useblocks/app/docs/ubtrace/
       image: ghcr.io/useblocks/ubtrace:latest
       depends_on:
         - vis-tree
         - oidc
       ports:
         - "7130:7130"
       working_dir: /
       environment:
         MESSAGE: 🌍 Starting ubTrace on http://localhost:7130
         PUBLIC_VIS_TREE_HOST: http://localhost:7140
         UBTRACE_SERVER_VIS_TREE_INTERNAL_HOST: http://vis-tree:7140
         UBTRACE_SERVER_AUTH_ISSUER_URL: http://localhost:7180
         UBTRACE_SERVER_AUTH_DISCOVER_URL: http://localhost:7180/.well-known/openid-configuration
   
   ################################
   # VIS-TREE
   ################################
     vis-tree:
       volumes:
         - ubtrace-data:/home/useblocks/app/docs/ubtrace/
       image: ghcr.io/useblocks/vis-tree:latest
       ports:
         - "7140:7140"
       depends_on:
         - oidc
       working_dir: /app
       environment:
         ORG: ${ORG:-useblocks}
         PROJECT: ${PROJECT:-showcase}
         VERSION: ${VERSION:-1}
         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
   
   ################################
   # OIDC Auth server
   ################################
     oidc:
       image: ghcr.io/useblocks/oidc:latest
       environment:
         LOCAL_OIDC_CLIENT_ID: ubtrace-client
         CORS_ALLOWED_ORIGINS: http://localhost:7130, http://127.0.0.1:7130
       command: python -m oidc_local_server.app
       ports:
         - "7180:8080"
       working_dir: /app
   
   ################################
   # 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 representation, used by ubTrace

   • OIDC: User identity server, used by ubTrace for user login. Can be replaced by any company ID 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/useblocks/app/docs/ubtrace/  # Prior config
       - ./my_docs/_build/ubtrace/:/home/useblocks/app/docs/ubtrace/
   

   Note: The syntax is LOCAL_PATH:SERVER_PATH.

   SERVER_PATH must be /home/useblocks/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.