RootTrace

Install RootTrace with Docker Compose

Docker Compose is the supported self-hosted deployment. The stack is nginx for TLS, the RootTrace server (API and dashboard), and MongoDB on one host.

Plan for about 30 minutes.

Only want to try it? The quickstart runs RootTrace on your laptop with two containers and no DNS name, certificate, or license. Come back here when you need something real users log into.

What you need

  • A Linux host with Docker Engine and the Compose v2 plugin: 4 vCPU, 8 GB RAM, 20 GB disk to start. Check the sizing guide for anything larger.
  • A DNS name pointing at the host, plus a certificate and private key for it.
  • cosign, from the official Sigstore release, to verify what you download.
  • The signed RootTrace deployment archive.
  • A license token, or the workspace that will issue you one.

Elasticsearch is optional and external. Skip it and everything works except semantic search.

1. Download and verify the release

Open the release descriptor from the signed-in self-hosted portal:

https://packages.roottrace.io/releases/latest.json

Download the five versioned URLs it names (bundleUrl, checksumUrl, signatureUrl, publicKeyUrl, manifestUrl) into one empty directory, then verify the archive before extracting it:

sha256sum -c roottrace-deployment-<version>.tar.gz.sha256
cosign verify-blob \
  --key roottrace-cosign.pub \
  --insecure-ignore-tlog=true \
  --signature roottrace-deployment-<version>.tar.gz.sig \
  roottrace-deployment-<version>.tar.gz
tar -xzf roottrace-deployment-<version>.tar.gz
cd roottrace-deployment-<version>

Stop if either check fails. On macOS use shasum -a 256 -c for the first line.

Now verify the images the archive points at:

./verify-images.sh

That script checks the server and agent signatures and their CycloneDX SBOM attestations against the same key. RootTrace signs with a private KMS key and does not publish to the Rekor transparency log, which is why the tlog check is skipped; the signatures themselves are still verified.

Use release/release-manifest.json from this verified archive as the record of what you deployed.

2. Configure

cd deploy
cp .env.example .env
chmod 600 .env

Generate the secrets, each one distinct:

mkdir -p secrets
openssl rand -hex 32 > secrets/app_secret
chmod 700 secrets
chmod 600 secrets/app_secret

openssl rand -hex 32   # MONGO_ROOT_PASSWORD
openssl rand -hex 32   # MONGO_APP_PASSWORD
openssl rand -hex 32   # ROOTTRACE_BOOTSTRAP_TOKEN
openssl rand -hex 32   # ROOTTRACE_METRICS_BEARER_TOKEN

Hexadecimal matters for the Mongo passwords: they are interpolated into a MongoDB URI, and URI-reserved characters break it.

Then fill in .env. These are the values with no safe default:

# Images: the signed digests from release/release-manifest.json
ROOTTRACE_IMAGE=public.ecr.aws/byteaffinity/roottrace/server@sha256:REPLACE
ROOTTRACE_COLLECTOR_IMAGE=public.ecr.aws/byteaffinity/roottrace/agent@sha256:REPLACE

# Secrets generated above
MONGO_ROOT_PASSWORD=
MONGO_APP_PASSWORD=
ROOTTRACE_BOOTSTRAP_TOKEN=
ROOTTRACE_METRICS_BEARER_TOKEN=

# Public identity: the exact HTTPS origin users open
ROOTTRACE_PUBLIC_APP_URL=https://roottrace.example.com
ROOTTRACE_PUBLIC_API_URL=https://roottrace.example.com/api
ROOTTRACE_ALLOWED_ORIGINS=https://roottrace.example.com
ROOTTRACE_JWT_ISSUER=https://roottrace.example.com
ROOTTRACE_WEBAUTHN_RP_ID=roottrace.example.com
ROOTTRACE_WEBAUTHN_ORIGINS=https://roottrace.example.com

The server refuses to start on-prem in production without the public identity values, and the JWT issuer must equal the origin of the API URL. Everything else in .env.example has a working default; the configuration reference explains each one.

Two optional pieces, if you need them now:

  • Email. Set ROOTTRACE_EMAIL_SENDING_ENABLED=true with ROOTTRACE_SMTP_HOST, ROOTTRACE_SMTP_PORT, ROOTTRACE_SMTP_USERNAME, and ROOTTRACE_SMTP_PASSWORD. You can create the first account without it and add SMTP before inviting anyone else.
  • A license bound to a known installation id. Set ROOTTRACE_INSTALLATION_ID to that exact id. Leave it empty and RootTrace generates one on first boot for the license to be issued against.

3. Add TLS material

Put the certificate chain and key in deploy/certs/, with these exact names:

deploy/certs/host.crt
deploy/certs/host_key.pem

Use your CA or internal PKI in production. deploy/certs/README.md has a self-signed pair for getting the stack up first.

4. Start

From deploy/:

docker compose config -q
docker compose pull
docker compose up -d
docker compose ps

Wait for MongoDB, the API, and nginx to report healthy. config -q only checks interpolation and YAML. It does not validate RootTrace settings or connectivity, so watch the logs if the API does not come up:

docker compose logs --since 10m roottrace

The log names the exact rejected setting or unreachable dependency.

Then confirm the endpoint users will open:

curl --fail --silent --show-error \
  --cacert /path/to/roottrace-ca.pem \
  https://roottrace.example.com/readyz

It must report ready: true with a healthy MongoDB check.

5. First sign-in

Restrict the HTTPS listener to your own address until MFA is enrolled.

Open https://roottrace.example.com and create the owner account:

  1. Choose a local username, not an email address, and enter ROOTTRACE_BOOTSTRAP_TOKEN from .env. No email or confirmation is needed. You are signed in immediately and public registration locks itself.
  2. Enroll TOTP in Settings → Account security and store the recovery codes. A local owner has no email password-reset path, so this is the only way back in.
  3. Paste the license token into the license panel; it shows the installation id to bind the license to. A valid license is required before the first workspace.
  4. Create the first workspace.

Keep the bootstrap token in your secret manager. With TOTP or a recovery code it is the break-glass path for local password recovery, and it cannot claim a second account. Rotate it by changing the value and restarting the API when someone who knew it leaves.

Then open the listener to its normal audience.

6. Before you rely on it

  • Take a backup and test the restore: scripts/mongo_backup.sh /secure/roottrace-backups, then scripts/mongo_restore.sh into an isolated environment. Keep secrets/app_secret with the backup: JWT keys and integration secrets are unreadable without it.
  • Add users. SMTP invitations create accounts; without SMTP, provision with SCIM. SSO authenticates existing accounts but does not create them.
  • Install a collector and confirm ingest.
  • Scrape /metrics with Authorization: Bearer <ROOTTRACE_METRICS_BEARER_TOKEN>.
  • Read the hardening guide if you have a compliance baseline to meet.

Read the upgrade guide before you ever change an image digest.

Installing on a host with no internet access? Follow the air-gapped guide instead of this page.