Skip to main content
This quickstart runs LightShip with Docker Compose against a ClickHouse instance that already contains your OpenTelemetry traces, then walks through the first sign-in, table binding, and trace query.

​
Prerequisites

  • Docker and Docker Compose.
  • A local LightShip checkout. See Install LightShip. Run the commands in Start LightShip from the checkout root.
  • Read-only credentials to the ClickHouse instance that holds your OTel traces. ClickHouse is not included in the Compose stack.
  • Common DSN forms:
ClickHouse DSN

​
Start LightShip

1

Configure the environment

Copy the example environment file and set CLICKHOUSE_DSN. Every other variable has a working default for evaluation.
Edit .env and set:
.env
2

Bring up the stack

On first boot LightShip applies Postgres migrations and, if LIGHTSHIP_ADMIN_PASSWORD_HASH is empty, generates a bootstrap admin password and prints it to the log exactly once.
3

Sign in as admin

Open http://localhost:8080 and sign in as admin with the password from the log. You are required to change it before accessing traces, the Connect page, MCP, or admin routes.
The bootstrap password is printed to the container log once. Restarts do not reprint it. If you lose it, generate a replacement hash with lightship hash and set LIGHTSHIP_ADMIN_PASSWORD_HASH in .env. See Admin recovery.

​
Connect your trace data

1

Discover tables

Open Setup → Connect data. LightShip ranks likely trace tables and suggests the required field mappings.
2

Confirm the required columns

Choose the trace table and confirm the five required columns:
  • trace_id
  • timestamp
  • span_id
  • parent_span_id
  • name
3

Mark policy and filter fields

Choose whether each trace field is Searchable, available to Access rules, or both. LightShip displays the field type discovered from the source; number fields are search-only.

​
Run your first query

Create a personal API key from Connect, then call the traces query endpoint. Filters are an ANDed list of conditions.
Only traces where at least one span satisfies both the caller’s policies and the filter are returned. Use next_cursor to page through large result sets.

​
Next steps

Define roles and policies

Express access rules over span attributes and user attributes.

Connect an MCP client

Investigate traces conversationally from Claude Code or Codex.

Offline analysis

Export authorized rows for jq, DuckDB, or scripts without filling the conversation.

API reference

Every REST endpoint, request shape, and error.