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)

  • ~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 ubt_sphinx

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 ubt_sphinx

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

By default, ubTrace runs in free tier mode and only grants access to the useblocks demo organization. To use your own organization name, you need a license. Contact support@useblocks.com to request one. 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: