Quickstart: Docker

docker --version         # Should show 20.10 or higher
docker compose version   # Should show 2.0 or higher

git clone https://github.com/use-lumina/Lumina.git
cd Lumina/infra/docker

docker compose up -d

docker compose ps

NAME                 STATUS
lumina-postgres      Up (healthy)
lumina-redis         Up (healthy)
lumina-nats          Up (healthy)
lumina-ingestion     Up (healthy)
lumina-api           Up (healthy)
lumina-dashboard     Up (healthy)

http://localhost:3000

npm install @uselumina/sdk

import { initLumina } from '@uselumina/sdk';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces',
  service_name: 'quickstart-test',
});

async function main() {
  console.log('Sending test trace...');

  const response = await lumina.traceLLM(
    async () =>
      anthropic.messages.create({
        model: 'claude-sonnet-4-5',
        max_tokens: 100,
        messages: [
          { role: 'user', content: 'Say hello in one sentence.' },
        ],
      }),
    {
      name: 'hello-claude',
      system: 'anthropic',
      prompt: 'Say hello in one sentence.',
    }
  );

  console.log('✓ Trace sent successfully!');
  console.log('→ View at: http://localhost:3000/traces');
}

main();

npx tsx test-trace.ts

Sending test trace...
✓ Trace sent successfully!
→ View at: http://localhost:3000/traces

curl -X POST http://localhost:9411/v1/traces \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [{
          "key": "service.name",
          "value": { "stringValue": "curl-test" }
        }]
      },
      "scopeSpans": [{
        "spans": [{
          "traceId": "00000000000000000000000000000001",
          "spanId": "0000000000000001",
          "name": "test-span",
          "startTimeUnixNano": "'$(date +%s)000000000'",
          "endTimeUnixNano": "'$(date +%s)500000000'",
          "attributes": [
            { "key": "model", "value": { "stringValue": "claude-sonnet-4-5" } },
            { "key": "prompt_tokens", "value": { "intValue": "10" } },
            { "key": "completion_tokens", "value": { "intValue": "20" } },
            { "key": "cost_usd", "value": { "doubleValue": 0.0015 } }
          ]
        }]
      }]
    }]
  }'

# Stop services
docker compose down

# Edit .env file
cat > .env <<EOF
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
EOF

# Restart with new config
docker compose --env-file .env up -d

DASHBOARD_PORT=3000      # Change to avoid conflicts
API_PORT=8081
INGESTION_PORT=9411

docker compose down
docker compose up -d

# .env
TRACE_RETENTION_DAYS=7   # Delete traces older than 7 days
DAILY_TRACE_LIMIT=50000  # Max traces per day

# Find process using port
lsof -i :3000

# Kill process (replace PID)
kill -9 <PID>

docker compose logs <service-name>

# Examples:
docker compose logs ingestion
docker compose logs postgres

# Check PostgreSQL logs
docker compose logs postgres | grep "ready to accept connections"

# Restart ingestion service
docker compose restart ingestion

curl http://localhost:8081/health

{"status":"ok","service":"lumina-api"}

docker compose logs api

docker compose logs ingestion | grep ERROR

const lumina = initLumina({
  endpoint: 'http://localhost:9411/v1/traces', // Correct
  // NOT: http://localhost:8081 (that's the query API)
});

# Stop Docker services
docker compose down

# Start infrastructure only (Postgres, Redis, NATS)
docker compose up -d postgres redis nats

# Run services locally with hot reload
cd ../../services/ingestion && bun run dev
cd ../../services/api && bun run dev
cd ../../apps/dashboard && bun run dev

# All services
docker compose logs -f

# Specific service
docker compose logs -f ingestion

# Stop services and remove volumes (deletes all data)
docker compose down -v

# Restart fresh
docker compose up -d

# Stop services (keeps data)
docker compose down

# Stop and remove all data
docker compose down -v