Configuration

The configuration of ubTrace is divided in two parts:

• Server configuration: Runtime settings for the ubTrace deployment. In the current NestJS-based stack (v1.0.0+), the server is configured through environment variables in the .env file and docker-compose.yml. See Installation for the full list of environment variables.

• Project configuration: Project-specific options, which are taken from the currently selected/viewed project only. It allows to have project-specific colors, layouts and other important features. Stored inside ubtrace_project.toml and partly in conf.py.

Server Options (Legacy)

Deprecated since version 1.0.0: The ubtrace_server.toml options and UBTRACE_SERVER_* environment variables below apply to the legacy Python-based ubTrace server (pre-1.0) and have no effect in the current NestJS-based stack.

The current stack (v1.0.0+) is configured through the .env file with variables such as OIDC_ISSUER, DATABASE_URL, REDIS_HOST, etc. See Installation for the complete environment variable reference.

Legacy ubtrace_server.toml options (click to expand)

The options below were stored inside ubtrace_server.toml and used by the legacy Python server. The file is still generated by the Sphinx builder but is no longer read by the NestJS backend. Project discovery is based solely on ubtrace_project.toml files.

• project_src_dir: Absolute path to root directory of project source files. Env: UBTRACE_SERVER_PROJECT_SRC_DIR

• db_path: SQLite database file path (.db extension). Env: UBTRACE_SERVER_DB_PATH

• db_mode: Database init mode (new, wipe, update). Env: UBTRACE_SERVER_DB_MODE

• default_org: Default organization ID. Env: UBTRACE_SERVER_DEFAULT_ORG

• default_project_id: Default project ID. Env: UBTRACE_SERVER_DEFAULT_PROJECT_ID

• default_project_version: Default project version. Env: UBTRACE_SERVER_DEFAULT_PROJECT_VERSION

• multi_project: Enable multi-project support (true/false). Env: UBTRACE_SERVER_MULTI_PROJECT

• dir_layout: Directory layout (simple or versioned). Env: UBTRACE_SERVER_DIR_LAYOUT

• auth_required: Enable authentication (true/false). Env: UBTRACE_SERVER_AUTH_REQUIRED

• enable_project_scoped_auth: Scope auth to individual projects. Env: UBTRACE_SERVER_ENABLE_PROJECT_SCOPED_AUTH

• auth_client_id: OIDC client ID. Env: UBTRACE_SERVER_AUTH_CLIENT_ID

• auth_client_secret: OIDC client secret. Env: UBTRACE_SERVER_AUTH_CLIENT_SECRET

• auth_issuer_url: OIDC issuer URL. Env: UBTRACE_SERVER_AUTH_ISSUER_URL

• auth_discovery_url: OIDC discovery endpoint URL. Env: UBTRACE_SERVER_AUTH_DISCOVERY_URL

• auth_access_token_params: Additional access token request params (JSON). Env: UBTRACE_SERVER_AUTH_ACCESS_TOKEN_PARAMS

• auth_authorize_params: Additional authorization request params (JSON). Env: UBTRACE_SERVER_AUTH_AUTHORIZE_PARAMS

• chat_enabled: Enable AI chat feature (true/false). Env: UBTRACE_SERVER_CHAT_ENABLED

• openrouter_apikey: API key for OpenRouter AI service. Env: UBTRACE_SERVER_OPENROUTER_APIKEY

• search_enabled: Enable search (true/false). Env: UBTRACE_SERVER_SEARCH_ENABLED

• debug: Enable debug mode (true/false). Env: UBTRACE_SERVER_DEBUG

• security_config_file: Path to RBAC config TOML file. Env: UBTRACE_SERVER_SECURITY_CONFIG_FILE

• sidebar_apps_config: Sidebar app URLs (dashboard, traceability_tree). Env: UBTRACE_SERVER_SIDEBAR_APPS_CONFIG

Project Options

Project-specific configuration is stored in a file called ubtrace_project.toml. This file is normally available after the ubtrace Builder has built the documentation.

For convenience reasons the options from ubtrace_project.toml can be also set in the conf.py file of the project, which allows to deal with all documentation-related tasks in the Sphinx-way of doing things.

ubTrace configuration flow

ubtrace_project.toml Example

[ubtrace]
enable_website_mode = false
header_navigation_links = []

[ubtrace.docs_sources]
"/dev/architecture" = ".rst"
"/dev/autodiscover" = ".rst"
"/dev/changelog" = ".rst"
"/features/multi_project" = ".rst"
"/index" = ".rst"
"/installation" = ".rst"
"/license" = ".rst"
"/quickstart" = ".rst"
"/usage/sphinx/configuration" = ".rst"
"/usage/sphinx/index" = ".rst"
"/usage/sphinx/protection" = ".rst"
"/usage/sphinx/users" = ".rst"
"/usage/ubt_server" = ".rst"

[ubtrace.global_nav_extra]

[ubtrace.hide_left_sidebar]

[ubtrace.hide_right_sidebar]
"/usage/sphinx" = true

[ubtrace.page_header_styles]
minimal = []
modern = []

[ubtrace.project]
author = "team useblocks"
base_url = "."
copyright = "2025, team useblocks"
html_favicon = "_static/favicon.ico"
html_logo = ""
name = "ubtrace"
organization = "useblocks"
project_id = "ubtrace_docs"
root_doc = "index"
version = "1"

[ubtrace.secure]

[ubtrace.secure_perms]

[ubtrace.theme_options]
content_theme = "alabaster"
edit_uri = "/edit/main/docs/source/"
header_style = "modern"
hide_left_sidebar = false
hide_right_sidebar = false
mode = ""
name = ""
repo_url = "https://github.com/example/repo"
view_source_uri = "/blob/main/docs/source/"

[ubtrace.theme_options.content_theme_options]

[ubtrace.theme_options.html_sidebars]
"**" = ["localtoc.html"]

[ubtrace.theme_options.logo]
desktop = ""
mobile = ""

ubtrace_build_kuzudb

Deprecated since version KuzuDB: generation is no longer needed. The backend now uses PostgreSQL + Elasticsearch with NDJSON files generated by the ubt-coverage Rust CLI. This option is ignored and will be removed in a future release.

Option to enable or disable the build of the Kuzu database.

Default: False.

ubtrace_enable_website_mode

Option to enable or disable the website mode feature for a ubt_sphinx project. This option accepts a boolean value (True/False).

Note

When you set the ubtrace_enable_website_mode option to True, the following changes will be applied to the website:

• The left sidebar area will be removed.

• The right sidebar area will be removed.

• The “Edit” and “View Source” links will be removed from the top of the page.

Default: False

Usage

# File: conf.py
ubtrace_enable_website_mode = True

Important

It is recommended to configure the header_navigation_links and the header_style configuration options, when you set the ubtrace_enable_website_mode option to True. This ensures that there is sufficient data available to create the navigation links. Otherwise, the website will not have any navigation links in the header.

ubtrace_organization

Option to set the organization ID for a ubt_sphinx multi-project instance.

Default: user.

ubtrace_project

Option to set the project ID for a ubt_sphinx multi-project instance.

Default: project.

ubtrace_version

Option to set the version ID for a ubt_sphinx multi-project instance.

Default: 1.

ubtrace_theme_options

A dictionary of options that influence the look and feel of the ubTrace theme.

Usage

# File: conf.py
ubtrace_theme_options = {
   "content_theme": "sphinx_immaterial",
   "content_theme_options": {},
   "edit_uri": "edit/main/docs/",
   "global_nav_extra": {
      "ubtrace_site": {"name": "ubTrace Main", "url": "https://www.ubTrace.com/"},
   },
   "header_navigation_links": [
      {
         "title": "Documentation",
         "url": "/docs/",
      },
      {
         "title": "ubTrace Website",
         "children": [
            {
               "title": "Home",
               "url": "https://www.ubTrace.com/",
               "class": "border border-white",
            },
            {
               "title": "Components",
               "url": "https://www.ubTrace.com/components/",
            },
         ],
      },
      {
         "title": "Our Story",
         "url": "https://www.ubTrace.com/our-story/",
      },
   ],
   "header_style": "modern",
   "hide_left_sidebar": False,
   "hide_right_sidebar": True,
   "html_sidebars": {"**": ["localtoc.html"]},
   "logo": {"desktop": "" or {}, "mobile": "" or {}},
   "mode": "dark",
   "name": "ubtheme",
   "repo_url": "https://github.com/useblocks/app",
   "view_source_uri": "/blob/main/docs/",
}

Below are the options understood by the ubTrace theme.

content_theme

The content_theme option sets the HTML “theme” to use when building with the Sphinx HTML builder. This option’s value is set as the value for the html_theme Sphinx config.

Default: 'alabaster'.

Usage

# File: conf.py
ubtrace_theme_options = {
   "content_theme": "sphinx_immaterial",
}

content_theme_options

The content_theme_options option sets the HTML “theme” options to use when building with the Sphinx HTML builder. This option’s value is set as the value for the html_theme_options Sphinx config.

Default: {}.

Usage

# File: conf.py
ubtrace_theme_options = {
   "content_theme_options": {},
}

edit_uri

The edit_uri option sets the URL segment for the “Edit” icon in the documentation. When combined with repo_url, it creates a link that allows users to edit the source file of any documentation page.

The value for edit_uri typically follows the format "edit/<branch name>/<docs source folder>".

Default: "" (empty string, which disables the “Edit” icon)

Note

The “Edit” icon only appears when all these conditions are met:

• The repo_url option is set

• The page doesn’t have the :hide_edit_link: metadata

• The docs sidebar app is selected as the ubtrace sidebar app

Usage

# File: conf.py
ubtrace_theme_options = {
   "edit_uri": "edit/main/docs/source/",
}

global_nav_extra

Option to add custom links to the global navigation menu of your ubTrace documentation.

global_nav_extra accepts a dictionary object. Each item in the dictionary represents a navigation link that contains the name and url.

Note

• The links will be displayed in the global navigation menu.

• The name and url key-value pairs must be provided or the link won’t be added to the menu.

• The links will open in a new browser tab when clicked.

Usage

# File: conf.py
ubtrace_theme_options = {
   "global_nav_extra": {
      "ubtrace_site": {"name": "ubTrace Main", "url": "https://www.ubTrace.com/"},
   },
}

In the example above, a custom link is added to the global_nav_extra option:

• ubTrace Main: A link named “ubTrace Main” pointing to “https://www.ubTrace.com/”.

Note

The data provided to global_nav_extra is stored in the ubtrace_project.toml file. For instance, the example code above will convert into:

# File: ubtrace_project.toml
[global_nav_extra]
[global_nav_extra.ubtrace_site]
name = "ubTrace Main"
url = "https://www.ubTrace.com/"

Tip

If you wish to update the extra navigation links from the global_nav_extra configuration without rebuilding the Sphinx app, you can edit the global_nav_extra data in ubtrace_project.toml and restart the server to apply changes to the global navigation menu.

header_navigation_links

The header_navigation_links configuration option specifies the navigation links displayed in the header of the site. It accepts a list of dictionary objects, where each dictionary represents a distinct navigation link.

Properties of the dictionary objects:

• title (string): The text to display as the label for the navigation link.

• url (string): The URL to which the navigation link should point. This can be an internal or external reference. External URLs must include the appropriate protocol (e.g., http:// or https://).

• children (list): An optional list of dictionary objects representing sub-navigation links. Each dictionary in the children list must include a title and a url.

• class (string): An optional property that accepts CSS class names, separated by space, to style the navigation links. You can use Tailwind CSS class names to style navigation links.

Note

• To get a responsive web interface, the maximum number of navigation links must be 4. If you provide more than 4 navigation links, we will select only the first 4 navigation links and ignore all others.

• Also, if a dictionary object includes both url and children, the navigation setup prioritizes the children and instead of creating a direct link, we create a link to trigger the sub-menu.

• If a dictionary object includes the class property, we add the value specified to the class attribute of an anchor or button tag (i.e. <a class=""> and <button class="">)

An example configuration for header_navigation_links might look like this:

Usage

# File: conf.py
ubtrace_theme_options = {
   "header_navigation_links": [
      {
         "title": "Documentation",
         "url": "/docs/",
      },
      {
         "title": "ubTrace Website",
         "children": [
            {
               "title": "Home",
               "url": "https://www.ubTrace.com/",
            },
            {
               "title": "Components",
               "url": "https://www.ubTrace.com/components/",
            },
            {
               "title": "Editor",
               "url": "https://www.ubTrace.com/components/editor",
            },
         ],
      },
      {
         "title": "Our Story",
         "url": "https://www.ubTrace.com/our-story/",
         "class": "border border-white"
      },
   ],
}

Important

It is important to configure header_navigation_links if you set the header_style configuration option or the header_style metadata option to minimal. This ensures that there is sufficient data available to create the navigation links.

header_style

The header_style option specifies the styling of the documentation header. Currently, it accepts two values: minimal or modern.

Default: "modern"

• minimal - The minimal header style integrates the data from the header_navigation_links configuration into the documentation’s header as navigation links. This style is recommended for pages intended to serve as landing pages.

  

  Desktop & Mobile view for the minimal header style

• modern - The modern header style offers a simple and elegant design, making it an ideal choice for documentation pages. It is the default setting for the header_style option.

  

  Desktop & Mobile view for the modern header style

Usage

# File: conf.py
ubtrace_theme_options = {
   "header_style": "minimal",
}

Note

If a page sets the header_style metadata option, it takes precedence over this option.

hide_left_sidebar

Option to hide the global navigation sidebar shown on the left side of the each page. By default, the navigation menu is shown if the browser viewport is sufficiently wide.

Default: False

Usage

# File: conf.py
ubtrace_theme_options = {
   "hide_left_sidebar": False,
}

Note

If a page sets the hide_left_sidebar metadata option, it takes precedence over this option.

hide_right_sidebar

Option to hide the local table of contents shown on the right side of the page. By default, the local table of contents is shown if the page contains sub-sections and the browser viewport is sufficiently wide.

Default: False

Usage

# File: conf.py
ubtrace_theme_options = {
   "hide_right_sidebar": True,
}

Note

If a page sets the hide_right_sidebar metadata option, it takes precedence over this option.

html_sidebars

The html_sidebars option sets the HTML “theme” sidebars to use when building with the Sphinx HTML builder. This option’s value is set as the value for the html_sidebars Sphinx config.

Default: {}.

Usage

# File: conf.py
ubtrace_theme_options = {
   "html_sidebars": {"**": ["localtoc.html"]},
}

logo

The logo option sets the website logo for both mobile and desktop screens. You can also set the logo for both light and dark modes for either desktop or mobile screens.

This option accepts the following key-value pairs:

• mobile (the logo to use for small screens) - path to mobile logo file

• desktop (the logo to use for large screens) - path to desktop logo file

or it also accepts:

• mobile (the logo to use for small screens) - a dictionary containing the logos for both light and dark modes

• desktop (the logo to use for large screens) - a dictionary containing the logos for both light and dark modes

Note

• The logo file path must be a relative path to the documentation source directory.

• The logo file can be any of the image formats supported by Sphinx.

• We use the html_logo Sphinx config value, if you don’t provide a logo for either the desktop or mobile screens.

Default: {"desktop": "", "mobile": ""}.

Usage

# File: conf.py
ubtrace_theme_options = {
   "logo": {
      "desktop": "_static/azuredevops-logo-dk.png",
      "mobile": "_static/azuredevops-logo-mb.png",
   },
}

# OR

# File: conf.py
ubtrace_theme_options = {
   "logo": {
      "desktop": {
            "light": "_static/useblocks_light.svg",
            "dark": "_static/useblocks_dark.svg",
      },
      "mobile": {
            "light": "_static/useblocks_mobile_light.svg",
            "dark": "_static/useblocks_mobile_dark.svg",
      },
   },
}

name

Important

The name option is deprecated in the latest version.

Use the name option to set the theme for the website. You can choose from one of the supported themes listed below:

• “skeleton”

• “wintry”

• “modern”

• “rocket”

• “seafoam”

• “vintage”

• “sahara”

• “hamlindigo”

• “gold-nouveau”

• “crimson”

• “ubtheme”

Note

Depending on the value you provide for the name option, we apply the following changes to the website:

• If you don’t specify the name option in conf.py, we use the most recent theme stored in your browser.

• If you specify the name option in conf.py and the value is a supported theme, we use that theme and remove the theme menu from the website’s theme settings drawer.

• If you specify both the mode and name options, we remove the theme settings tab from the navbar and the theme settings drawer.

Default: "" (i.e., an empty string).

Usage

# File: conf.py
ubtrace_theme_options = {
   "name": "ubtheme",
}

mode

Important

The mode option is deprecated in the latest version.

Use the mode option to set the theme mode for the website. This option accepts only two values:

• “dark”

• “light”

Note

Based on the value you provide for the mode option, we apply the following changes to the website:

• If you don’t specify the mode option in conf.py, we set the theme mode to light mode by default.

• If you specify the mode option in conf.py with either “dark” or “light”, we use the specified mode and remove the theme mode switch from the website’s theme settings drawer.

• If you specify both the mode and the name options, we remove the theme settings tab from the navbar and the theme settings drawer.

Default: "" (i.e., an empty string).

Usage

# File: conf.py
ubtrace_theme_options = {
   "mode": "dark",
}

repo_url

The link to the repository where the documentation source files are stored. This option is required to enable both the “Edit” and “View Source” links in the documentation.

The value for repo_url typically can be a URL to a repository hosting service such as GitHub, GitLab, or Bitbucket.

Default: "" (empty string, which disables the “Edit” and “View Source” links)

Usage

# File: conf.py
ubtrace_theme_options = {
   "repo_url": "https://github.com/useblocks/app",
}

view_source_uri

The view_source_uri option sets the URL segment for the “View Source” icon in the documentation. When combined with repo_url, it creates a link that allows users to view the source code of any documentation page.

The value for view_source_uri typically follows the format "/blob/<branch name>/<docs source folder>".

Default: "" (empty string, which disables the “View Source” icon)

Note

The “View Source” icon only appears when all these conditions are met:

• The repo_url option is set

• The page doesn’t have the :hide_view_source_link: metadata

• The docs sidebar app is selected as the ubtrace sidebar app

Usage

# File: conf.py
ubtrace_theme_options = {
   "view_source_uri": "/blob/main/docs/",
}

ubtrace_secure_perms

Define permissions to use for secured pages or folders. The value for the secure_perms is a list of dictionaries and can be aggregated from the “secure.permissions” key in the ubtrace_project.toml file.

Usage

# File: ubtrace_project.toml
[[secure.permissions]]
perm_uid = "lic_user"
name = "License User"
description = "Read pages open to license users"
level = "read"

# File: conf.py
ubproject_toml = tomllib.loads("ubtrace_project.toml").read_text("utf8")
ubtrace_secure_perms = ubproject_toml["secure"]["permissions"]
# OR
ubtrace_secure_perms = [
   {
      "lic_user": {
         "name": "License User",
         "description": "Read pages open to license users",
         "level": "read",
      },
   },
]

ubtrace_secure_pattern

Define regular expression for secured page or folder with user role. The value for the roles must be one or more user roles defined in the security configuration (Keycloak realm roles).

Usage

# File: conf.py
ubtrace_secure_pattern = {
   "user_manuals/ubm/": ["authenticated"],
   "^ukcs\S+HONEY$": ["int_developer"],
}

Page Metadata Options

In ubTrace, we use the Sphinx page metadata feature to set predefined or custom fields that provide information about a specific document.

This metadata is typically defined at the top of a reStructuredText (reST) file and can include a variety of details that influence how the page is processed or displayed.

The list of page metadata options supported by ubTrace Sphinx are:

• header_style

• hide_edit_link

• hide_view_source_link

• hide_left_sidebar

• hide_right_sidebar

header_style

The header_style metadata option specifies the header style to use for a particular page. It accepts only two values: minimal or modern.

This option works just like the header_style option under the ubtrace_theme_options configuration.

To set the header style of a page, you can add the header_style option to the top of the page using the syntax below:

Usage

RST

:header_style: minimal

MD

---
header_style: minimal
---

Note

If a page sets the header_style metadata option, it takes precedence over the header_style option under the ubtrace_theme_options configuration.

hide_edit_link

When specified, this option hides the “Edit” link at the top of the page. By default, the “Edit” link appears if the edit_uri option is set in the configuration. This metadata option overrides the global setting for the current page.

Usage

RST

:hide_edit_link:

MD

---
hide_edit_link: true
---

Tip

This option is commonly used on automatically-generated pages since they don’t have an editable source document.

hide_view_source_link

When enabled, this option hides the “View Source” link at the top of the page. By default, the “View Source” link appears if the view_source_uri option is set in the configuration. This metadata option overrides the global setting for the current page.

Usage

RST

:hide_view_source_link:

MD

---
hide_view_source_link: true
---

hide_left_sidebar

If this option is set to true, it hides the global navigation sidebar shown on the left side of the page. Otherwise, if it set to false, it shows the global navigation sidebar.

To hide/show the left sidebar of a page, you can add the hide_left_sidebar option to the top of the page using the syntax below:

Usage

RST

:hide_left_sidebar: true

MD

---
hide_left_sidebar: true
---

Note

If a page sets the hide_left_sidebar metadata option, it takes precedence over the hide_left_sidebar option under the ubtrace_theme_options configuration.

hide_right_sidebar

If this option is set to true, it hides the local table of contents shown on the right side of the page. Otherwise, if it set to false, it shows the local table of contents.

By default the local table of contents is shown if the page contains sub-sections and the browser viewport is sufficiently wide.

To hide/show the right sidebar of a page, you can add the hide_right_sidebar option to the top of the page using the syntax below:

Usage

RST

:hide_right_sidebar: true

MD

---
hide_right_sidebar: true
---

Note

If a page sets the hide_right_sidebar metadata option, it takes precedence over the hide_right_sidebar option under the ubtrace_theme_options configuration.