Getting Started

This tutorial walks you through deploying ubTrace from the offline bundle, logging in for the first time, importing a sample Sphinx project, and exploring the result in the web UI. By the end you will have a running ubTrace instance with real documentation data.

Time to complete: ~15 minutes.

Prerequisites

Before you begin, make sure you have:

  • Docker Engine 24+ with Compose v2 installed

  • The ubTrace offline bundle (ubtrace-offline-bundle-*.tar.gz)

  • ubt-sphinx >= 0.6.0 from the useblocks package index (for building Sphinx documentation)

  • ~5 GB of free disk space for Docker images

  • A terminal with make available

Tip

To verify your Docker setup:

docker compose version
# Docker Compose version v2.x.x

If you see v1.x or command not found, upgrade Docker Desktop or install the Compose plugin.

Step 1: Extract and load the bundle

Extract the offline bundle and load the Docker images into your local daemon.

tar xzf ubtrace-offline-bundle-*.tar.gz
cd ubtrace-offline-bundle-*

# Load all Docker images (~5 GB, takes 1-2 minutes)
./offline-load.sh ubtrace-images-*.tar.gz

Verify the images were loaded:

docker images | grep ubtrace

You should see images for ub-backend, ub-frontend, ub-worker, ub-builder, and keycloak-theme.

Step 2: Configure environment

Create your .env file from the bundled template:

make init

This copies .env.example to .env. Open it and replace the password placeholders with strong, unique values:

vim .env

Replace these <CHANGE-ME> placeholders:

  • POSTGRES_PASSWORD – application database password

  • KC_DB_PASSWORD – Keycloak database password

  • KEYCLOAK_ADMIN_PASSWORD – Keycloak admin console password

  • REDIS_PASSWORD – cache password

Important

Leave OIDC_CLIENT_SECRET unchanged. The bundled Keycloak realm ships with a pre-configured secret that must match. Changing it without also updating Keycloak will break authentication. See Installation for details.

Step 3: Start ubTrace

Start all services:

make up

Wait for all services to become healthy (this takes 30-60 seconds on first start):

make status

You should see output similar to:

NAME                  STATUS
ubtrace-postgres      healthy
ubtrace-keycloak      healthy
ubtrace-redis         healthy
ubtrace-es            healthy
ubtrace-api           healthy
ubtrace-frontend      healthy
ubtrace-builder       running
ubtrace-worker        running

Note

macOS / Apple Silicon: If Elasticsearch fails with a seccomp error, see Platform Notes for the workaround.

If any service is unhealthy, check its logs:

make logs SERVICE=ubtrace-api

Step 4: Log in

Open the ubTrace frontend in your browser:

http://localhost:7155

You will be redirected to the Keycloak login page. Log in with the pre-created test user:

Username

test

Password

Test1234!

After login, you will see the ubTrace landing page. There is no documentation data yet – that comes in the next step.

Warning

The test user is for initial verification only. Before going to production, delete it and create your own users. See Keycloak / OIDC Hardening in the Installation guide.

Step 5: Clone a sample project

ubTrace needs Sphinx documentation to display. For this tutorial, you will use the open-source sphinx-needs-demo project.

Clone the demo project and install its dependencies (requires internet). The demo project uses uv for dependency management:

git clone https://github.com/useblocks/sphinx-needs-demo
cd sphinx-needs-demo
uv sync
uv pip install --index-url https://pypi.useblocks.com "ubt-sphinx>=0.6.0"

Tip

If you are not using uv, create a virtual environment manually:

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
pip install -e .
pip install --index-url https://pypi.useblocks.com "ubt-sphinx>=0.6.0"

Step 6: Configure conf.py for ubTrace

Add the ubTrace builder extension and project identifiers to the demo’s docs/conf.py. Append the following lines at the end of the file:

# --- ubTrace integration ---
extensions.append("ubt_sphinx")

ubtrace_organization = "useblocks"
ubtrace_project = "sphinx-needs-demo"
ubtrace_version = "1"

These three values (ubtrace_organization, ubtrace_project, ubtrace_version) define how the project appears in ubTrace’s organization/project/version hierarchy. See Configuration for all available options.

Step 7: Build with the ubTrace builder

Build the documentation using the ubtrace builder. Make sure you run this from within the virtual environment where ubt_sphinx is installed:

# If using uv:
uv run sphinx-build -b ubtrace docs docs/_build/ubtrace

# If using a manual venv (make sure it is activated):
sphinx-build -b ubtrace docs docs/_build/ubtrace

This generates the ubTrace output structure under docs/_build/ubtrace/, including the needs.json data file, document files, and ubtrace_project.toml configuration.

Step 8: Import into ubTrace

Import the built output into your running ubTrace instance:

# Go back to the ubTrace bundle directory
cd /path/to/ubtrace-offline-bundle-*

make import-build \
  SRC=/path/to/sphinx-needs-demo/docs/_build/ubtrace/useblocks/sphinx-needs-demo/1 \
  ORG=useblocks \
  PROJECT=sphinx-needs-demo \
  VERSION=1

The ub-worker service automatically detects the new data and loads it into PostgreSQL and Elasticsearch. Watch the progress:

make logs SERVICE=ubtrace-worker

Wait until you see a message indicating the import completed successfully (typically under a minute for the demo project).

Step 9: Explore the documentation

Refresh your browser at http://localhost:7155. You should now see the imported project available.

Select the project:

  1. Choose organization useblocks

  2. Choose project sphinx-needs-demo

  3. Choose version 1

You can now explore ubTrace’s features:

  • Documentation viewer – browse the rendered Sphinx pages

  • Traceability tree – visualize connections between Sphinx-Needs objects (requirements, specifications, test cases)

  • Schema validation – view any schema violations in the project

  • Search – full-text search across all documentation and Sphinx-Needs objects

Tip

Try the traceability tree: select a need type (e.g., req or spec), enter a filter term, and explore how requirements link to specifications and test cases.

Step 10: Import your own project

Now that you have verified ubTrace works, import your own Sphinx project.

Option A: Sphinx source files (ubTrace builds for you)

make import-src \
  SRC=./path/to/your/sphinx-project \
  ORG=yourcompany \
  PROJECT=your-project \
  VERSION=v1

Option B: Pre-built CI output (faster, recommended for CI/CD)

If your CI pipeline already builds with ubt_sphinx:

make import-build \
  SRC=./path/to/ci-output \
  ORG=yourcompany \
  PROJECT=your-project \
  VERSION=v1

Both methods auto-detect changes – no restart needed. See Installation for the full import documentation including required directory structures.

Important

A valid license is required to use ubTrace. Without one, all feature API endpoints are blocked. Contact support@useblocks.com to request a license. See Installation for license configuration details.

Clean up

To stop ubTrace and preserve your data for later:

make down

To stop ubTrace and delete all data (database, Elasticsearch index, imported artifacts):

make clean

To restart later with your data intact:

make up

Next steps

Now that ubTrace is running, explore these topics: