Local Development Setup

You can run the entire DeepTracer stack on your machine. This is useful for contributing to DeepTracer or testing your SDK integration locally before deploying.

Prerequisites

Docker — For ClickHouse and Redis
PostgreSQL — Running locally on port 5432
Node.js 20+ — For the dashboard
Bun — For the ingestion service

Architecture

The local stack has four parts:

Service	Port	Purpose
ClickHouse	8123	Stores logs, errors, traces, and LLM usage data
Redis	6379	Buffers incoming events before flushing to ClickHouse
Ingestion API	5147	Receives data from SDKs and writes to ClickHouse
Dashboard	5148	Next.js app — the UI you interact with

PostgreSQL runs natively on port 5432 (not inside Docker). It stores project settings, users, investigations, and other app data.

Setup

Start ClickHouse and Redis

From the repo root:

cd infra && docker compose up -d

This starts:

ClickHouse at localhost:8123 (HTTP) and localhost:9000 (native protocol)
Redis at localhost:6379

ClickHouse is configured with:

User: default
Password: dev_password
Database: codeword_logging

The init scripts in infra/clickhouse/ create all the required tables automatically on first start.

Run database migrations

The dashboard uses Prisma for PostgreSQL. Run migrations to set up the schema:

cd web && npx prisma migrate dev

This creates all the tables the dashboard needs — projects, users, investigations, API keys, etc.

Start the ingestion service

cd ingestion && bun run dev

The ingestion API starts on port 5147. It receives events from SDKs, buffers them in Redis, and a background worker flushes them to ClickHouse every 2 seconds.

Start the dashboard

cd web && npm run dev

The dashboard starts on port 5148. Open http://localhost:5148 in your browser.

Point the SDK at your local stack

Set these environment variables in the app you're monitoring:

.env.local

DEEPTRACER_KEY=dt_your_local_api_key
DEEPTRACER_ENDPOINT=http://localhost:5147

# For browser-side tracking
NEXT_PUBLIC_DEEPTRACER_KEY=dt_your_local_api_key
NEXT_PUBLIC_DEEPTRACER_ENDPOINT=http://localhost:5147

Create a project in your local dashboard first to get an API key.

Verify it works

Once everything is running, send a test event with curl:

curl -X POST http://localhost:5147/ingest/logs \
  -H "Authorization: Bearer dt_your_local_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "test",
    "logs": [{"level": "info", "message": "Hello from local!"}]
  }'

You should get back {"ok": true, "count": 1} and see the log appear in your local dashboard within a few seconds.

Quick reference

Service	URL	Credentials
Dashboard	`http://localhost:5148`	Sign up locally
Ingestion API	`http://localhost:5147`	Use your project's API key
ClickHouse HTTP	`http://localhost:8123`	`default` / `dev_password`
ClickHouse Native	`localhost:9000`	`default` / `dev_password`
Redis	`localhost:6379`	No password
PostgreSQL	`localhost:5432`	Your local Postgres credentials

Troubleshooting

ClickHouse won't start

Make sure port 8123 isn't already in use. Check Docker logs:

docker compose -f infra/docker-compose.yml logs clickhouse

"Table not found" errors

The ClickHouse init scripts should run automatically on first start. If tables are missing, restart the container:

cd infra && docker compose down && docker compose up -d

Ingestion returns 401

Make sure you've created a project in the local dashboard and are using the correct API key. The key must start with dt_.

On this page