UNS DataHub

Getting started

Run your first
UNS DataHub Runtime.

Install the Runtime, complete its guided setup, start the local stack, and verify that the DataHub is available.

Install → Configure → Start → Verify

01 / Requirements

Before you begin

The bootstrap is available for macOS, Linux, and Windows on Intel/AMD 64-bit and ARM64 hosts.

  • Container engine Docker or Podman with Compose support.
  • Runtime access During the private preview, approved read-only access to the Runtime release.
  • Image access Credentials for any private container images configured by the Runtime.

02 / Install

Install the Runtime

Choose your host platform. The public installer verifies the bootstrap binary before installing it, then uns-bootstrap install downloads and verifies the matching Runtime bundle.

Choose your platform 
curl -fsSL \
  https://github.com/uns-datahub/uns-datahub-bootstrap/releases/latest/download/install.sh |
  sh
"$HOME/.local/bin/uns-bootstrap" install

03 / First setup

Complete the setup wizard

A fresh bootstrap installation opens the Runtime wizard automatically. It creates or updates .env and prints the exact Compose commands for your choices.

  1. 1
    Choose the Runtime mode Use local infrastructure only, controller only, or both together.
  2. 2
    Choose the secret source Keep local values in .env or configure Infisical.
  3. 3
    Choose the Compose engine Let the wizard detect Docker or Podman, or select one explicitly.
  4. 4
    Confirm Runtime values Review the registry and, when local infrastructure is selected, the PostgreSQL settings.

Run the wizard again

macOS and Linux 
cd "$HOME/uns-datahub-runtime"
./bin/uns init -i
Windows PowerShell 
Set-Location "$HOME\uns-datahub-runtime"
.\bin\uns.cmd init -i

04 / Start and verify

Start the local stack

The wizard prints the correct command for the selected Runtime mode. For the self-contained both mode with Docker, run these commands from the Runtime directory: 

docker compose --env-file .env up -d
docker compose ps

With Podman, replace docker compose with podman compose. Wait until the required services are running and the controller reports a healthy state.

05 / Operations

Common Runtime commands

These examples use Docker and the self-contained both mode. Use the Compose file printed by the wizard for infrastructure-only or controller-only modes.

Check status docker compose ps
Follow all logs docker compose logs -f
Follow one service docker compose logs -f <service>
Stop the stack docker compose down

Runtime service names include postgres, mosquitto, caddy, questdb, and uns-datahub-controller.

06 / Troubleshooting

Resolve common setup issues

runtime target must be absent or empty

The default target already contains a Runtime. Re-running the bootstrap safely reuses the directory when it contains the same verified Runtime version. If the installed version differs from the version requested by the bootstrap, or the contents cannot be verified, installation stops before changing local files.

This protects .env, .secrets, configuration, volumes, and other local state from an implicit replacement.

Compare the installed and requested versions

macOS and Linux 
cat "$HOME/uns-datahub-runtime/VERSION"
"$HOME/.local/bin/uns-bootstrap" version
Windows PowerShell 
Get-Content "$HOME\uns-datahub-runtime\VERSION"
& "$HOME\.local\bin\uns-bootstrap.exe" version

Option 1: install side by side

Use another empty directory when you want to inspect the new Runtime without moving the current installation. Do not start both installations simultaneously unless their ports have been configured not to conflict.

macOS and Linux 
"$HOME/.local/bin/uns-bootstrap" install \
  --dir "$HOME/uns-datahub-runtime-next"
Windows PowerShell 
& "$HOME\.local\bin\uns-bootstrap.exe" install `
  --dir "$HOME\uns-datahub-runtime-next"

Option 2: keep a versioned backup

Move the current directory to a unique backup name, then install into the normal target. Nothing is deleted, and the previous configuration remains in the backup.

macOS and Linux 
runtime_dir="$HOME/uns-datahub-runtime"
version_file="$runtime_dir/VERSION"
test -f "$version_file" || { printf 'Runtime VERSION not found\n' >&2; exit 1; }
installed_version=$(tr -d '[:space:]' < "$version_file")
test -n "$installed_version" || { printf 'Runtime VERSION is empty\n' >&2; exit 1; }
backup_dir="${runtime_dir}-${installed_version}-$(date +%Y%m%d-%H%M%S)-backup"
test ! -e "$backup_dir" || exit 1
mv "$runtime_dir" "$backup_dir"
"$HOME/.local/bin/uns-bootstrap" install
Windows PowerShell 
$runtimeDir = "$HOME\uns-datahub-runtime"
$versionFile = "$runtimeDir\VERSION"
if (-not (Test-Path -LiteralPath $versionFile)) { throw "Runtime VERSION not found" }
$installedVersion = (Get-Content $versionFile -Raw).Trim()
if (-not $installedVersion) { throw "Runtime VERSION is empty" }
$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$backupDir = "$HOME\uns-datahub-runtime-$installedVersion-$stamp-backup"
if (Test-Path -LiteralPath $backupDir) { throw "Backup target exists: $backupDir" }
Move-Item -LiteralPath $runtimeDir -Destination $backupDir
& "$HOME\.local\bin\uns-bootstrap.exe" install
The Runtime download is denied

Confirm that your GitHub account has Runtime preview access. Use a fine-grained token limited to the Runtime repository with read-only Contents permission.

A container image cannot be pulled

Authenticate Docker or Podman to the configured container registry. Registry authentication is separate from the GitHub token used to download the Runtime.

A service does not become healthy

Run docker compose ps, then inspect the service with docker compose logs -f <service>. With Podman, use the equivalent podman compose command.

The local DataHub does not open

Confirm that the selected mode includes local infrastructure, that the caddy service is running, and that port 8180 is not already in use.

07 / Versioned guide

Continue with the bundled README

The installed Runtime includes the complete guide for its exact version: configuration details, Infisical, mode-specific operations, updates, administration, and troubleshooting.

macOS and Linux $HOME/uns-datahub-runtime/README.md
Windows $HOME\uns-datahub-runtime\README.md
Bootstrap reference Request preview access