LightShip runs as an HTTP service backed by Postgres for control-plane state and a read-only
ClickHouse connection for traces. Docker Compose is the quickest evaluation path; the same
container can run on a managed platform or container orchestrator.
Security boundary
LightShip enforces policies and audit logging only for requests that pass through it. Direct
ClickHouse access bypasses both controls.
Do not give policy-restricted users direct ClickHouse access. Treat ClickHouse credentials as
infrastructure secrets and use LightShip as their trace-data access point.
Production checklist
Before running LightShip in production, verify the following:
- Terminate TLS in front of LightShip, for example with a reverse proxy or load balancer.
- Use a read-only ClickHouse account and keep both database connection strings in a secret manager.
- Keep the admin password hash in a secret manager and inject it as
LIGHTSHIP_ADMIN_PASSWORD_HASH.
- Change the default
POSTGRES_PASSWORD before the first boot.
- Back up the Postgres volume regularly so user accounts, roles, and audit history are preserved.
- Apply per-client login and request rate limits at the edge; built-in concurrency limits are
per process.
- Monitor
GET /healthz for service and Postgres availability. ClickHouse is deliberately excluded
from this health check, so alert on trace-query failures separately.
- Keep
LIGHTSHIP_DEMO_MODE disabled outside a dedicated synthetic-data demo.
Review Limitations before exposing a deployment.
Multiple replicas
You can run multiple LightShip replicas behind a load balancer for high availability. Be aware of how configuration and role data propagate:
- Policy changes reach other replicas within
LIGHTSHIP_MODEL_TTL (default 1m). If an
expired cache cannot refresh, new model-dependent requests fail closed.
- Role assignments are read from the database on every request, so they take effect immediately across all replicas.