Skip to content

Installation

The fastest route is the interactive installer — it can stand up the monolith, the full per-service stack, connect a probe agent to an existing stack, or generate Kubernetes manifests for the monolith:

curl -fsSL https://tracedown.dev/install.sh | bash

It only needs Docker with the Compose plugin (kubectl for the Kubernetes mode), asks before touching anything, and every prompt can be pre-answered with a TD_* variable for unattended installs. The script is short and worth reading before piping, as any script should be — Interactive Installer documents every mode, prompt and variable.

Tracedown ships in two forms, and there are three ways to run it:

Path What it is Use it when
Quickstart (Docker) The development Compose stack, built from source. Trying Tracedown out, or developing it.
Production Deploy The full per-service stack, pulled from published release artifacts, fronted by your own web server. Running it for real, with probe agents where you need them.
Monolith The entire platform in a single jar — one process, dashboard included, probes executed in-process. Small installs that don't want eight services.

The per-service form is a set of JVM services, a Python probe agent, PostgreSQL, and Redis. The monolith is those same services in one JVM, needing only PostgreSQL and Redis. Both are the complete product — the difference is operational shape, and Monolith is candid about the trade.

Read these in order:

  1. Requirements — what you need before you start.
  2. Interactive Installer — the one-line route, and what it asks.
  3. Quickstart (Docker) — a running system in a few minutes.
  4. Production Deploy — the release-artifact stack behind your web server.
  5. Monolith — the single-jar edition.
  6. Architecture — what the services are and how they talk.
  7. Configuration — the full environment-variable reference.
  8. Database & Migrations — how schema changes are applied.
  9. Probe Agents — deploying agents and enrolling them over mTLS.

The development stack ships with development secrets

The Quickstart's .env.example contains a placeholder encryption key, a placeholder JWT secret, and a known demo password. They are fine for a local trial and unacceptable for anything reachable by other people. The Production Deploy refuses to start on placeholder secrets; before you expose anything to a network, work through Secrets & Encryption.

Which pieces are optional

Piece Needed?
PostgreSQL Required. System of record.
Redis A Required. Queues, outbox, sessions — persistent (AOF).
Redis B Required in practice. Cache and rate limiting; safe to lose.
Redis C Optional. Resource-hierarchy cache; disabled when REDIS_C_URL is empty.
Probe agent Required in the per-service stack — nothing probes without at least one. The monolith executes probes in-process and uses no agents.
S3-compatible storage Optional. Only if you want saved response bodies off local disk.
SMTP / Resend / Mailgun Optional, but without it no email leaves the system.

After installation

Once the stack is up — and, in the per-service form, an agent is enrolled — the User Manual covers creating your first service and probe. The Administration section covers the things you only think about once it is real: backups, certificate rotation, retention, and scaling.