Skip to main content
Prefer a managed solution? traceroot Cloud is maintained by the traceroot team — no setup required.
traceroot is open source and supports self-hosting. Run it on your own infrastructure for full control over your data and deployment. Some features require an enterprise license key.

Deployment Options

Local Developer Deployment

Best for: contributing to traceroot, local development, and debugging. Starts PostgreSQL, ClickHouse, MinIO, and Redis in Docker, then runs the API, UI, and workers locally via a tmux session.
traceroot local dev environment running in tmux
See the README and CONTRIBUTING.md for details.

Local Docker Deployment

Best for: trying traceroot locally, integration testing, or running a full stack without local dependencies. Runs the entire stack in containers using Docker Compose — no need to install Python, Node, or other runtimes locally.
See the README for details.

Credentials

make prod and make prod-lite create a .env file and fill in credentials for your install: the database and object store passwords, the auth and internal API secrets, and the key that encrypts stored model provider keys and Slack tokens (ENCRYPTION_KEY). Each install gets its own values. To use your own, set them in .env before starting; a value copied from .env.example is not accepted and the stack stops with a message naming the variable to change.
Keep a backup of .env. If ENCRYPTION_KEY is lost, stored model provider keys and Slack tokens can no longer be read and have to be entered again.
The object store API is published on 127.0.0.1 only. Put a reverse proxy in front of it deliberately if you need access from another machine.

Upgrading an existing install

  1. Pull the latest version and run make prod-lite (or make prod). This replaces any database or object store password in .env that was copied from .env.example with a generated one.
  2. If the stack stops and names ENCRYPTION_KEY, your .env still has the key from .env.example. Run make rotate-encryption-key once. It re-encrypts the stored model provider keys and Slack tokens under a new key in a single transaction, writes the new key to .env, and saves the previous one in the .env.encryption-key.d directory. If it fails before the database is updated, nothing is changed and you can run it again. If the database was updated but .env could not be written, the command says so and keeps the new key in .env.encryption-key.d/pending; fix the problem and run it again to finish. It refuses to run while ENCRYPTION_KEY is set in your shell environment or COMPOSE_ENV_FILES is set, because Docker Compose would then not use the key in .env. While a rotation is running, or has not finished, the make targets that start the stack wait or refuse, so the services never run with a key the database is being moved away from; to start the stack with docker compose yourself, finish the rotation first.
  3. Start the stack again with make prod-lite (or make prod). If you started it with make prod before, its tmux session is still there and make prod offers to re-attach to it; answer N so a new session is started. Re-attaching skips the setup and would leave the stopped services stopped.
Rotation stops the web, worker, agent, detector and billing services first. If it fails they stay stopped, and starting is refused until the rotation has finished: fix the problem and run make rotate-encryption-key again (to abandon an unfinished rotation that did not change the database, remove .env.encryption-key.d/pending and start as in step 3). An install that never set ENCRYPTION_KEY has nothing stored under it and simply gets a generated one.

Production Deployment

Best for: production workloads on AWS. Deploy traceroot on Kubernetes using Helm charts and Terraform. Configuration lives in the deploy directory.
Terraform deployment is currently experimental. We recommend testing thoroughly before production use.