RootTrace

Quickstart

Two containers, on your own machine. Three commands and a sign-up form.

Budget time for the first image pull rather than the setup: the server image is a little under 6 GB. Once it is on disk, the stack comes up in about a minute.

This is for trying RootTrace out: on a laptop, or a scratch VM. It has no TLS, no database password, and it listens on localhost only. When you want something real users log into, follow the install guide instead.

You do not need a DNS name, a certificate, a license, or a signed release archive for any of this.

What you need

Docker Desktop, or Docker Engine with the Compose v2 plugin. About 4 GB of free memory, and about 8 GB of free disk: the server image is a little under 6 GB unpacked, because it carries its own embedding model.

Check Compose is there:

docker compose version

1. Create the two files

Make an empty directory, cd into it, and paste this whole block. It writes the compose file and generates your bootstrap token in one go, with no editing and no placeholders to fill in:

cat > docker-compose.yml <<'COMPOSE'
name: roottrace-quickstart

services:
  mongo:
    image: mongo:8.0.28-noble
    restart: unless-stopped
    volumes:
      - mongo_data:/data/db
    healthcheck:
      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
      interval: 10s
      timeout: 5s
      retries: 12

  roottrace:
    image: public.ecr.aws/byteaffinity/roottrace/server:latest
    restart: unless-stopped
    depends_on:
      mongo:
        condition: service_healthy
    environment:
      ROOTTRACE_MONGO_URI: mongodb://mongo:27017/
      ROOTTRACE_BOOTSTRAP_TOKEN: ${ROOTTRACE_BOOTSTRAP_TOKEN:?create the .env file first}
    ports:
      - "127.0.0.1:${ROOTTRACE_PORT:-8090}:8090"
    healthcheck:
      test:
        - CMD
        - python3
        - -c
        - "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8090/readyz',timeout=5).status==200 else 1)"
      interval: 15s
      timeout: 10s
      retries: 20
      start_period: 90s

volumes:
  mongo_data:
COMPOSE

[ -f .env ] || printf 'ROOTTRACE_BOOTSTRAP_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env

That token is how you claim the first account in step 3. Compose reads .env automatically, so you never have to pass it on the command line.

The [ -f .env ] || is load-bearing: paste the block a second time without it and you overwrite the token while the container keeps running on the old one, so the file and the server disagree and nothing you copy will work.

If you already have a RootTrace release archive, the same file is in it as deploy/docker-compose.quickstart.yml, and you can skip writing it out:

cd deploy
printf 'ROOTTRACE_BOOTSTRAP_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env
docker compose -f docker-compose.quickstart.yml up -d

2. Start it

docker compose up -d

The first run has to pull that image, so give it time on a slow connection. Once it starts, the server spends another minute loading its model before it answers. Watch for both services to report healthy:

docker compose ps

If you would rather see it happen:

docker compose logs -f roottrace

3. Create your account

Open http://localhost:8090.

The sign-up form on a fresh installation asks for three things:

  1. A username, not an email address. Lowercase letters, digits, ., _ and -; at least 3 characters.
  2. A password, at least 8 characters.
  3. The bootstrap token. Read it out of the running container, so it is the value the server will actually check rather than whatever is in the file now:
   docker compose exec roottrace printenv ROOTTRACE_BOOTSTRAP_TOKEN

If that prints nothing, the container started before .env existed. Fix it with docker compose up -d --force-recreate, then read it again.

Submit, and you are signed in. There is no confirmation email to wait for, and no license to paste in. RootTrace creates your first workspace and closes sign-up behind you, so this form only works once.

That is the whole setup. Send it some data next: the collector guide for host metrics, or the APM SDK guide for application traces.

Stopping and starting

docker compose stop            # pause it, keep the data
docker compose up -d           # bring it back
docker compose down -v         # delete it, database included

down -v removes the volume, which means the account you just made is gone too. That is the fastest way to start over if you want to walk through setup again.

If something goes wrong

Port 8090 is already in use. Add a different port to .env and run docker compose up -d again:

echo 'ROOTTRACE_PORT=8095' >> .env

The page does not load and docker compose ps shows starting. Give it another minute. The server loads an embedding model into memory before it accepts connections, and on a first run that takes longer than you expect.

The sign-up form rejects you, or asks for something that is not on it. The form works exactly once: RootTrace closes sign-up as soon as an owner exists. If a previous attempt got that far (even one you thought failed), the bootstrap token is no longer consulted and no value will work. Check whether an account is already there:

docker compose exec mongo mongosh --quiet --eval 'db.getSiblingDB("roottrace").users.countDocuments({})'

Anything other than 0 means you already have an owner: sign in with it, or start over from an empty database. Starting over deletes everything RootTrace has stored, which on a quickstart is nothing you will miss:

docker compose down -v && docker compose up -d

First-owner setup credentials are invalid. The token in your .env is not what you typed into the form. Fix .env, then docker compose up -d to restart the server with the new value.

ROOTTRACE_BOOTSTRAP_TOKEN must contain at least 32 characters for an on-prem installation. The server refuses to start on a token below that length, so you never reach the setup form. openssl rand -hex 32 produces 64, which is fine.

required variable ROOTTRACE_BOOTSTRAP_TOKEN is missing a value. You are running Compose from a directory with no .env in it. cd to the directory holding the two files.

Anything else. The server explains itself in its own logs, including the exact setting it rejected:

docker compose logs --since 10m roottrace

Calling the API directly rather than using the dashboard? Every API route lives under /api, so http://localhost:8090/api/auth/registration-status, for example. The bare paths serve the dashboard, so a missing /api comes back as HTML or a 405.

What this leaves out

The quickstart is missing everything that makes a deployment safe to point real users at:

  • No TLS. Traffic is plain HTTP, which is why it binds to localhost.
  • No MongoDB authentication, and a single standalone node rather than a replica set.
  • No backups, and no verified restore.
  • No signature verification of the images it pulls, and a floating latest tag instead of a pinned digest.
  • No Elasticsearch, so semantic search is off. Everything else works.

Do not fix these one at a time. The install guide is the supported path and covers all of them, and deploy/docker-compose.yml is a different stack: nginx for TLS, an authenticated replica-set MongoDB, and pinned signed image digests.

One thing not to try: setting ROOTTRACE_ENVIRONMENT=prod on the quickstart stack. Production mode requires a sharded MongoDB and refuses to start against the standalone node here.

Moving to a real deployment

Nothing carries over, and that is the intended path. Read the install guide and build the production stack fresh; treat the quickstart as something you throw away with docker compose down -v.