Configuration¶

The configuration of ubTrace is divided in two parts:

Server configuration: Config options for the single, overall ubTrace instance, like the server port. Stored inside ubtrace_server.toml.
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¶

Server-related options are stored inside ubtrace_server.toml but could also be set in a .env file.

Following options are available:

auth_required: If true, authentication is enabled on the ubTrace server.
db_mode: The database mode to use.
db_path: The path to the database file.
debug: If true, debug mode is enabled.
default_project_id: The default project ID to use for multi-project support.
default_project_version: The default project version to use for multi-project support.
dir_layout: The directory layout to use for multi-project support.
enable_project_scoped_auth: If true, project-scoped authentication is enabled.
multi_project: If true, multi-project support is enabled.
port: The port on which the server listens.
project_src_dir: The source directory for the project.
search_enabled: If true, search is enabled.
secret_key: The secret key for the server.
security_config_file: The path to the security configuration file.
sidebar_apps_config: Configuration for the sidebar applications.
auth_client_id: The client ID for the authentication (required only when authentication is enabled).
auth_client_secret: The client secret for the authentication (required only when authentication is enabled).
auth_issuer_url: The issuer URL for the authentication (required only when authentication is enabled).
auth_discovery_url: The discovery URL for the authentication (required only when authentication is enabled).
auth_access_token_params: Additional parameters for the access token request (optional).
auth_authorize_params: Additional parameters for the authorization request (optional).

project_src_dir¶

(required)

Specifies the absolute path to the root directory where your ubTrace Server project source files are located.

Important

In a .env file, set env key as UBTRACE_SERVER_PROJECT_SRC_DIR.

Note

For multi-project setups, this directory should contain all project subdirectories.

db_path¶

(required)

Defines the database file path for the ubTrace Server instance. The DB file path must point to an SQLite database file with the .db extension (e.g., ubt_sec.db).

Important

In a .env file, set env key as UBTRACE_SERVER_DB_PATH.

Note

If the database file does not exist, it will be created automatically and stored under the project_src_dir when the server starts.
Ensure that the specified path is writable by the user running the ubTrace Server.

default_project_id¶

(required)

Defines the default project identifier for the ubTrace Server. This setting is used when no specific project ID is provided in the request.

Important

In a .env file, set env key as UBTRACE_SERVER_DEFAULT_PROJECT_ID.

auth_required¶

Controls whether authentication is enabled for the ubTrace Server instance.
When set to True (default), users must authenticate to access protected resources.
When set to False, authentication is disabled and the server allows anonymous access.

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_REQUIRED.

debug¶

Controls the debug mode for the ubTrace Server instance.
When set to True, enables the search feature for the ubTrace Server application.
When set to False (default), runs the server in production mode.

Important

In a .env file, set env key as UBTRACE_SERVER_DEBUG.

db_mode¶

Controls the database initialization mode for the ubTrace Server instance. Defaults to "new".

The following values are accepted for db_mode:

"new": Creates a new empty database
"wipe": Removes all existing data from the database
"update": Updates existing data while preserving the database structure

Important

In a .env file, set env key as UBTRACE_SERVER_DB_MODE.

multi_project¶

Controls whether multi-project support is enabled for the ubTrace Server instance.
When set to True, allows managing multiple projects within the server.
When set to False (default), runs in single-project mode.

Important

In a .env file, set env key as UBTRACE_SERVER_MULTI_PROJECT.

dir_layout¶

Specifies the directory layout configuration for the ubTrace Server instance when multi-project setup is enabled. Defaults to "".

The following values are accepted for dir_layout:

"simple": Organizes projects in a flat structure without version control
"versioned": Organizes projects in a hierarchical structure with version control support

Important

In a .env file, set env key as UBTRACE_SERVER_DIR_LAYOUT.

enable_project_scoped_auth¶

Controls whether project-scoped authentication is enabled for the ubTrace Server instance.
When set to True, authentication is scoped to individual projects.
When set to False (default), authentication applies globally across all projects.

Important

In a .env file, set env key as UBTRACE_SERVER_ENABLE_PROJECT_SCOPED_AUTH.

search_enabled¶

Controls the search feature for the ubTrace Server instance.
When set to True, enables the search feature for the ubTrace Server instance.
When set to False (default), disables the search feature.

Important

In a .env file, set env key as UBTRACE_SERVER_SEARCH_ENABLED.

port¶

Specifies the port number on which the ubTrace Server instance listens for incoming connections. Defaults to port 3000.

Note

Make sure the specified port is available and not used by other services on your system.

Important

In a .env file, set env key as UBTRACE_SERVER_PORT.

secret_key¶

Specifies the secret key used by the ubTrace Server instance for cryptographic operations. A secure random string is generated by default if not specified.

Note

For production deployments, it’s recommended to set a consistent secret key to ensure session persistence across server restarts.

Important

In a .env file, set env key as UBTRACE_SERVER_SECRET_KEY.

default_project_version¶

Specifies the default project version for ubTrace Server. Defaults to "".

Note

This setting is only required when both:

multi_project is enabled
dir_layout is set to "versioned"

Important

In a .env file, set env key as UBTRACE_SERVER_DEFAULT_PROJECT_VERSION.

security_config_file¶

The security_config_file specifies the path to a TOML file containing Role-Based Access Control (RBAC) configurations for the ubTrace Server. This file defines organizations, projects, permissions, roles, teams, and their relationships.

Structure of the security config file:

organizations: Defines organizations and their unique identifiers

projects: Maps projects to organizations

roles: Defines roles and their associated permissions

teams: Specifies teams, their members, roles and organization access

This configuration enables:

Organization-based access control
Role-based permissions
Team membership management
Project access restrictions

Important

In a .env file, set env key as UBTRACE_SERVER_SECURITY_CONFIG_FILE.

To configure authentication, you need to set the following ubt_server options:

auth_client_id¶

Specifies the client ID provided by your OpenID Connect (OIDC) provider. Defaults to "".

Note

This setting is required when configuring authentication for the ubTrace server. You must obtain a valid client ID from your authentication provider.

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_CLIENT_ID.

auth_client_secret¶

Specifies the client secret provided by your OpenID Connect (OIDC) provider. Defaults to "".

Note

This setting is required when configuring authentication for the ubTrace server. You must obtain a valid client secret from your authentication provider. Keep this value secure and never commit it to version control.

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_CLIENT_SECRET.

auth_issuer_url¶

The client URL for the OIDC provider. Defaults to "".

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_ISSUER_URL.

auth_discovery_url¶

The OIDC discovery endpoint URL that provides configuration information for the OIDC provider. Defaults to "".

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_DISCOVERY_URL.

auth_access_token_params¶

Specifies additional parameters to be included in requests to the access token endpoint.

Defaults to None.

Note

Consult your authentication provider’s documentation for supported parameters.

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_ACCESS_TOKEN_PARAMS.

Provide the parameters as a JSON string in your .env file:

UBTRACE_SERVER_AUTH_ACCESS_TOKEN_PARAMS='{"param":"value"}'

auth_authorize_params¶

Specifies additional parameters to include in the authorization endpoint URL when redirecting users for authentication.

Defaults to None.

Note

Consult your authentication provider’s documentation for supported parameters.

Important

In a .env file, set env key as UBTRACE_SERVER_AUTH_AUTHORIZE_PARAMS.

Provide the parameters as a JSON string in your .env file:

UBTRACE_SERVER_AUTH_AUTHORIZE_PARAMS='{"param":"value"}'

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.

../_images/ubtrace_config_flow.drawio.png — ubTrace configuration flow¶

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_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, 3 additional links are provided to the global_nav_extra option:

Admin Dashboard: A link named “Admin Dashboard” pointing to “/admin/”.
DB Control Area: A link named “DB Control Area” pointing to “/control/”.
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.toml file. For instance, the example code above will convert into:

# File: ubTrace.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.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.

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¶

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¶

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 ubproject.toml file.

Usage

# File: ubproject.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("ubproject.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_config_file configuration.

Usage

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

Customizing the layout¶

You can customize the ubTrace theme by overriding Jinja template blocks found in the “layout.html.j2” template. Follow the steps below to make these customizations:

First, create a “ubtrace_theme/” folder in your project’s “/_templates” directory (usually located in the “docs” directory)

mkdir docs/_templates/ubtrace_theme

Note

The ubTrace theme exclusively gathers custom theme files from the “_templates/ubtrace_theme/” directory.

Next, place a “layout.html.j2” file in the “ubtrace_theme/” directory.

touch docs/_templates/ubtrace_theme/layout.html.j2

Then, configure your ‘conf.py’ to include the “_templates” path:

templates_path = ['_templates']

Finally, edit your override file at docs/_templates/ubtrace_theme/layout.html.j2:

{# Import the ubTrace theme's base template file. #}
{% extends 'base.html.j2' %}
{# Customize the HTML title #}
{% block htmltitle %}Page Title{% endblock %}
{% block extrahead %}
{# Add custom content to the <head> HTML tag #}
{% endblock %}

{% block extracontent %}
{# Add custom content to the <body> HTML tag #}
{% endblock %}

{% block footer %}
   {# Add a custom <footer> tag to the HTML page #}
{% endblock %}

Available Blocks¶

The ubTrace theme provides several blocks you can use:

description_meta: Adds content for the description metadata (i.e. <meta name="description" content="">)
htmltitle: Adds content for the HTML <title> tag.
extrahead: Adds extra metadata, links, styles, scripts, etc to the <head> tag.
extracontent: Appends custom HTML to the <body> tag.
footer: Adds a custom <footer> tag to the HTML page.
extrascript: Adds extra <script> tags to the end of the <body> tag on the page.

Tip

You can specify the HTML element you will like to use for page scrolling by setting the page_scroll_selector variable:

{# Set the selector to use for page scrolling #}
{% set page_scroll_selector = "body" %}

Note

For more information about using Jinja templates to customize the layout, see the Template Inheritance section of the Jinja documentation.

Configuration¶

Server Options¶

project_src_dir¶

db_path¶

default_project_id¶

auth_required¶

debug¶

db_mode¶

multi_project¶

dir_layout¶

enable_project_scoped_auth¶

search_enabled¶

port¶

secret_key¶

default_project_version¶

sidebar_apps_config¶

security_config_file¶

auth_client_id¶

auth_client_secret¶

auth_issuer_url¶

auth_discovery_url¶

auth_access_token_params¶

auth_authorize_params¶

Project Options¶

ubtrace_enable_website_mode¶

ubtrace_theme_options¶

content_theme¶

content_theme_options¶

edit_uri¶

global_nav_extra¶

header_navigation_links¶

header_style¶

hide_left_sidebar¶

hide_right_sidebar¶

html_sidebars¶

logo¶

name¶

mode¶

repo_url¶

view_source_uri¶

ubtrace_secure_perms¶

ubtrace_secure_pattern¶

Page Metadata Options¶

header_style¶

hide_edit_link¶

hide_view_source_link¶

hide_left_sidebar¶

hide_right_sidebar¶

secure¶

Customizing the layout¶

Available Blocks¶