Prefer a managed solution? traceroot Cloud is maintained by the traceroot team — no setup required.
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.
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.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.
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
- Pull the latest version and run
make prod-lite(ormake prod). This replaces any database or object store password in.envthat was copied from.env.examplewith a generated one. - If the stack stops and names
ENCRYPTION_KEY, your.envstill has the key from.env.example. Runmake rotate-encryption-keyonce. 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.ddirectory. If it fails before the database is updated, nothing is changed and you can run it again. If the database was updated but.envcould 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 whileENCRYPTION_KEYis set in your shell environment orCOMPOSE_ENV_FILESis set, because Docker Compose would then not use the key in.env. While a rotation is running, or has not finished, themaketargets 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 withdocker composeyourself, finish the rotation first. - Start the stack again with
make prod-lite(ormake prod). If you started it withmake prodbefore, its tmux session is still there andmake prodoffers to re-attach to it; answerNso a new session is started. Re-attaching skips the setup and would leave the stopped services stopped.
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 thedeploy directory.