Server configuration reference

Operational settings of the RootTrace server container can be overridden with environment variables at startup (docker run -e or Compose environment:). Most are read once at process start. The selected deployment security profile is also stored through the platform-admin UI and validated against the running configuration before the update is accepted. The database-backed profile and JWT algorithm do not require an API restart. This page lists the operator-facing variables for an on-prem deployment. For the supported end-to-end path, start with the Docker Compose install guide.

Select the server image from the RootTrace Server Amazon ECR Public Gallery. The public Gallery shows the supported tags and pull commands. Air-gapped installations must mirror that image and the RootTrace Agent image before configuring the server to generate collector install instructions.

Minimal configuration

Configure these runtime connectivity settings before first use. Browser identity, the application secret, the first-owner bootstrap token, and the metrics token are also required for the production first-boot flow described in the install guide.

The supported Compose stack supplies these settings, runs MongoDB on an internal-only network, mounts the application-secret file, and terminates TLS at nginx. Set its required values in deploy/.env; do not copy a partial standalone docker run command into production.

Where settings come from

On-prem, there is one source: the container environment. Compose reads deploy/.env and maps selected values in; the application never opens that file itself.

An on-prem image does not contact AWS Systems Manager Parameter Store unless you explicitly set a prefix. Leave these unset; the supported Compose stack and every air-gapped deployment do:

If you do opt in: parameters live one per Standard SecureString under the prefix, names must begin with ROOTTRACE_, and an existing environment variable always wins over the same-named parameter, even when it is empty. Parameter Store only fills what the environment left missing. The workload role needs ssm:GetParametersByPath on that path and nothing more. scripts/import_env_to_parameter_store.py migrates an existing env file (--dry-run first; it prints names, never values).

Conventions

• Booleans accept 1, true, yes, on (case-insensitive).
• List values are comma-separated.
• Integer variables are parsed strictly; a non-numeric value fails startup.
• Published images have cloud or on_prem compiled into a root-owned, read-only native module. There is no runtime deployment-mode setting. Packaged startup fails if the marker is missing or invalid. A source checkout may use ROOTTRACE_DEPLOYMENT_MODE for local development; Docker uses the same name only as a build argument.

Core runtime

Do not set ROOTTRACE_SKIP_STARTUP_BOOTSTRAP, ROOTTRACE_RUN_EMBEDDING_WORKER_IN_API, or ROOTTRACE_EMBEDDING_SERVICE_MODE: the server's own bootstrap process manages these for its worker and sidecar children.

Data stores

Security and auth

The API exposes WebAuthn enrollment and assertion endpoints, but the current Flutter client does not yet manage passkeys. Use TOTP for accounts operated through the shipped client. A passkey-only account can use one of its saved single-use recovery codes at login.

Workspace security administration

Workspace owners and admins configure tenant-applicable controls in Flutter under Settings → Security & Compliance:

• security_profile: default, regulated, or air_gapped
• privileged MFA
• idle-session timeout
• failed-login threshold and lockout duration
• concurrent-session cap
• inactive-account disable period
• logon consent banner and text

Blank numeric values inherit the deployment defaults. For users in several workspaces, RootTrace applies the strictest applicable session/account value.

The same screen shows the effective deployment profile, FIPS/JWT and WebAuthn state, token lifetimes, password policy, rate limiting, audit chaining, external-secret and metrics authentication posture, request limits, embedding/email posture, Elasticsearch TLS, proxy/CDN trust, browser origins, private egress exceptions, collector-token lifetime, and direct TLS. Those values are read-only to workspace admins because they belong to the shared API process. Changing them per tenant would not reconfigure the proxy, OpenSSL provider, or server socket. Platform admins can select the deployment security profile and JWT signing algorithm in Flutter without restarting the API. The profile is accepted only when the current process controls satisfy it. JWT changes rotate the shared database signing key before the update returns.

Licensing

The verification key is compiled into src/roottrace_license.py. The private key never leaves AWS KMS. The RootTrace Cloud runtime identity needs kms:Sign and kms:GetPublicKey on that key. Customer installs need no AWS credentials. ROOTTRACE_FIPS_MODE=true makes the KMS client use the regional AWS FIPS endpoint.

Grant the RootTrace Cloud runtime role only the operations it uses:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "SignRootTraceLicenses",
    "Effect": "Allow",
    "Action": ["kms:Sign", "kms:GetPublicKey"],
    "Resource": "arn:aws:kms:us-east-1:123456789012:key/REPLACE_WITH_KEY_ID"
  }]
}

For local cloud development, configure a named AWS CLI profile, preferably through IAM Identity Center, and expose only its name and the non-secret configuration to the process:

aws configure sso --profile roottrace-license-signing
aws sso login --profile roottrace-license-signing
export AWS_PROFILE=roottrace-license-signing
export AWS_DEFAULT_REGION=us-east-1
export ROOTTRACE_LICENSE_KMS_KEY_ID=alias/roottrace-license-signing
export ROOTTRACE_LICENSE_KMS_REGION=us-east-1

Confirm the profile and then start the source checkout in cloud mode from the same shell:

aws sts get-caller-identity --profile roottrace-license-signing
export ROOTTRACE_DEPLOYMENT_MODE=cloud

RootTrace reads the process environment and does not load .env_dev or another dotenv file itself. The launcher must export these values before importing the application.

The profile belongs to that host user. A container does not inherit the host's AWS profile. Do not work around that by mounting credentials or passing access keys into the customer Compose stack: the published on-prem image cannot issue licenses. Run local cloud development as the configured host user, or attach a workload role to the cloud compute service.

Do not write AWS access or session keys to a dotenv file or Parameter Store. Production cloud deployments use their workload identity. Customer on-prem deployments do not receive these settings.

Email

Setting ROOTTRACE_SMTP_HOST switches all mail to direct SMTP through your relay, bypassing every cloud path. Leaving it empty with the relay disabled means email is simply not sent.

On an empty on-prem database, the first owner can register with a local username, the configured bootstrap token, and no email address. The account is confirmed locally, public registration locks automatically, and the account has no email password-reset path. Keep the bootstrap token in the deployment secret manager and enroll TOTP; password recovery requires both that token and a current authenticator or recovery code. Later password-based users need SMTP-backed invitations. Sites without SMTP must provision users and memberships with SCIM; SSO alone does not create an account.

AI, LLM, and embeddings

The OpenAI-compatible base URL is resolved from inside the API container or pod. Use the model server's network hostname. localhost only works when the model server shares the API container's network namespace.

The image also disables all third-party telemetry unconditionally (DO_NOT_TRACK, HF_HUB_DISABLE_TELEMETRY, and related flags).

Self-monitoring (APM)

The server can monitor itself with the same APM pipeline your own services use.

The Compose template passes all six settings and defaults ROOTTRACE_API_URL to http://127.0.0.1:8090/api, keeping self-monitoring inside the API container. After first sign-in, create a collector token and set it as ROOTTRACE_APM_TOKEN; leave the token empty to keep self-monitoring disabled.

Rate limiting and ingest

Collectors and fleet

Retention and audit

Webhooks and notifications

Webhook URLs must use HTTPS by default and cannot contain URL credentials. The HTTP client checks every DNS answer on every connection, does not cache DNS, and applies the same policy after redirects. Responses are bounded before parsing or recording.

ROOTTRACE_NOTIFICATION_ALLOW_INSECURE_WEBHOOKS=true permits HTTP webhook URLs and disables webhook TLS verification. It does not permit private destinations. For an internal receiver you must separately list its network in ROOTTRACE_OUTBOUND_ALLOWED_PRIVATE_CIDRS.

Example for two explicitly approved internal networks:

ROOTTRACE_OUTBOUND_ALLOWED_PRIVATE_CIDRS=10.40.8.0/24,fd00:40:8::/64

Use narrow service subnets. Do not allow metadata, loopback, or an entire VPC when a smaller range is available.

API request and metrics security

The request limits are enforced while reading the ASGI body, before FastAPI, Pydantic, JSON, protobuf, or webhook-signature parsing. They apply to requests with Content-Length and to chunked transfer encoding. Endpoint-specific ceilings remain stricter for client errors, log ingest, OTLP, and Stripe webhooks. A reverse proxy can impose a lower limit; keep its tested body limit at least as large as the largest enabled ingest request.

Configure a high-entropy metrics token through the deployment's secret manager:

ROOTTRACE_METRICS_BEARER_TOKEN="$(openssl rand -hex 32)"
curl -fsS \
  -H "Authorization: Bearer $ROOTTRACE_METRICS_BEARER_TOKEN" \
  http://127.0.0.1:8090/metrics

/readyz and /healthz/ remain unauthenticated so orchestrator probes can use them. Keep both on an internal listener or restrict them at the proxy/firewall.

Repository links

There is no SSH identity to configure here. Each repository link carries its own deploy key, generated in the app when you create the link; you install the public half as a read-only deploy key on the repository host. Nothing else in the server opens an SSH connection.

Repository SSH destinations use the same private-network CIDR policy as webhooks. Before ls-remote, clone, or fetch, RootTrace resolves every address, rejects the destination if any answer is non-public and not explicitly allowed, and pins SSH to the validated address while retaining the original hostname for host-key verification.

Branding, OEM, and public URLs

Compose-level variables

These are read by deploy/docker-compose.yml itself (interpolation), not by the application:

Cloud-internal variables

These drive the hosted service and do nothing on an on-prem install. Leave them unset; they are listed only so you can recognize them in a settings dump.