System Requirements

This page describes the requirements for running a self-hosted ubTrace instance.

Operating System

ubTrace runs as a set of Docker containers and supports any platform where Docker Engine is available:

  • Linux (recommended for production) – any modern distribution with Docker Engine 24+ and Compose v2.

  • macOS – supported via Docker Desktop. See Platform Notes for Apple Silicon notes.

  • Windows – supported via Docker Desktop with WSL 2 backend.

Docker

ubTrace requires:

  • Docker Engine 24+ (or Docker Desktop 4.x which includes it)

  • Docker Compose v2 (included with Docker Engine 24+ and Docker Desktop)

Verify your installation:

docker --version          # Docker Engine 24+
docker compose version    # Compose v2.x

Hardware

Resource

Minimum

Recommended

CPU

4 cores

8 cores

RAM

8 GB

16 GB

Disk

20 GB

50 GB

The minimum configuration is suitable for evaluation and small teams. For production deployments with large documentation sets or many concurrent users, use the recommended configuration or higher.

Note

Disk usage depends on the number and size of imported documentation projects. The values above include space for Docker images (~5 GB), database storage, and Elasticsearch indexes.

Services & Ports

A ubTrace deployment consists of the following services:

Service

Image

Port

Role

ubtrace-api

ghcr.io/useblocks/ub-backend

7150

NestJS API server

ubtrace-frontend

ghcr.io/useblocks/ub-frontend

7155

Next.js web UI

ubtrace-keycloak

quay.io/keycloak/keycloak:26.4.0

7181

Authentication (OIDC)

ubtrace-elasticsearch

elasticsearch:9.3.0

7184

Search & analytics

ubtrace-db

postgres:16-alpine

internal

Application database

ubtrace-keycloak-db

postgres:16-alpine

internal

Keycloak database

ubtrace-redis

redis:7-alpine

internal

Cache & sessions

ubtrace-builder

ghcr.io/useblocks/ub-builder

internal

Sphinx build service

ubtrace-worker

ghcr.io/useblocks/ub-worker

internal

Data pipeline (NDJSON processing)

ubtrace-api-migrate

ghcr.io/useblocks/ub-backend-migrate

–

Database migration (init container)

ubtrace-keycloak-theme

ghcr.io/useblocks/keycloak-theme

–

Keycloak theme (init container)

Services marked internal do not expose ports to the host by default. Init containers run once at startup and then exit.

Ensure that ports 7150, 7155, 7181, and 7184 are available on your host, or change the defaults via environment variables (see Environment Variables).

Browser

The ubTrace web UI supports modern browsers:

  • Google Chrome (latest)

  • Mozilla Firefox (latest)

  • Microsoft Edge (latest)

  • Apple Safari (latest)

JavaScript must be enabled.

Cloud Deployment (Upcoming)

Cloud-native deployment support is planned but not yet available. The following approaches are under development:

  • OpenTofu / Terraform for cloud resource provisioning (#595)

  • Cloud-Init for instance bootstrap (#596)

  • Ansible for Day-2 configuration management (#597)

Target platforms include AWS, GCP, and Azure. Until then, ubTrace is deployed as a self-hosted Docker Compose stack – see Installation.