Configuration

Configuration is environment-driven. Set only the values your deployment needs, but treat the required auth, database, model, and public-origin values as production secrets.

Runtime requirements

• A supported deployment path: Docker Compose, the repository Terraform stack (Railway + Neon), or AWS CDK
• PostgreSQL 17; the reference Compose image is pgvector on Postgres 17
• A graph database; FalkorDB is included in the reference Compose stack
• An SMTP provider for transactional email
• An OpenRouter, Azure, Bedrock, or OpenAI-compatible model provider
• A public HTTPS origin for production auth callbacks, webhooks, MCP, and Forge remotes

Docker Compose

Clone the repository and copy the example environment file:

git clone https://github.com/ctxpipe-ai/ctxpipe.git
cd ctxpipe
cp docker-compose.env.example .env

Edit .env with your values. The full production-style stack is the Compose deploy profile:

pnpm start

The deploy profile starts Postgres, FalkorDB, migrator, backend, worker, UI, and codesearch. It does not start an OpenTelemetry collector. The backend listens on the public app port and proxies the UI.

Required variables

Email

Social sign-in

All social providers are optional. Omit the variables to disable that provider.

See Authentication for OAuth and session behavior.

Models and embeddings

See Model configuration for provider-specific examples and embedding requirements.

Graph database

See Graph databases for provider support and tenancy behavior.

GitHub App connector

Repository connectors use a deployment-owned GitHub App. The in-product wizard stores its ID, PEM private key, and webhook secret encrypted for the connection.

The wizard reserves the connection-specific webhook URL and provides the exact value to paste into GitHub.

See GitHub for App registration, permissions, events, credentials, installation, and end-to-end verification.

Atlassian and Confluence

Self-hosted Confluence uses the same product wizard as fully managed ctx|, but your deployment or organization must provide Atlassian and Forge settings first.

See Confluence & Atlassian for the full operator flow.

Slack

Self-hosted Slack uses one deployment-owned Slack app. Organizations authorize that app; they do not create per-tenant Slack apps or Event Subscription URLs.

Set the client ID, client secret, and signing secret together, then restart or redeploy backend. Backend and worker must share the same AUTH_SECRET and, when configured, CONNECTION_SECRETS_ENCRYPTION_KEY so encrypted Slack bot tokens remain usable by background capture jobs.

Set the Slack Event Subscriptions Request URL to:

https://<public-origin>/api/v1/webhook/slack

See Slack for scopes, app_mention Events, and intent-based thread capture.

Linear

Linear can store the OAuth application and webhook signing secret on the connection (Register in the product UI). LINEAR_* is an optional deployment-wide fallback.

See Linear for application registration, webhook subscriptions, preview limitations, and troubleshooting.

Notion

Notion uses one deployment-owned public integration and one deployment webhook subscription.

Put the OAuth credentials on every service that performs token refresh or connector work, then register the single deployment webhook. See Notion for provisioning and verification.

PagerDuty

PagerDuty can use a deployment-owned OAuth application. After a user authorizes an account, ctx| creates the signed webhook subscription. These variables are an optional hosted-style shortcut; self-host can save the app on the connection in the setup wizard instead.

There is no PAGERDUTY_WEBHOOK_SECRET. Per-subscription signing secrets are stored encrypted on the connection.

See PagerDuty for application registration and verification.

Observability

Telemetry is off until you set it. ctx| does not ship a collector, Langfuse, or ClickStack in the Compose deploy profile or in @ctxpipe/aws-cdk. Unset values keep logs on stdout and do not start trace or metric export. Empty values are treated as unset.

Point the signal URLs at your own OTLP/HTTP backend. Export starts from these variables. Include the signal path on each URL.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.example.com/v1/traces
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otel.example.com/v1/logs
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otel.example.com/v1/metrics
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer xxx

deployment.environment on backend traces, metrics, and logs, the Langfuse environment tag, codesearch, and the UI relay is RAILWAY_ENVIRONMENT_NAME when that is set, otherwise deployment.environment from OTEL_RESOURCE_ATTRIBUTES, otherwise production when NODE_ENV=production, otherwise development. Backend and codesearch also set service.namespace=ctxpipe. Codesearch always exports service.name codesearch.

LLM spans are OpenTelemetry spans. The apps do not read LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, or LANGFUSE_HOST. A Langfuse project accepts traces at https://<your-langfuse>/api/public/otel/v1/traces with Authorization=Basic <base64(publicKey:secretKey)> in OTEL_EXPORTER_OTLP_HEADERS. @ctxpipe/aws-cdk takes one base otel.endpoint and appends /v1/traces, /v1/logs, and /v1/metrics; see AWS.

Browser telemetry

The UI enables browser telemetry only when OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is set on the UI server. The browser posts traces to the same origin at /.otel/v1/traces. The relay also accepts /.otel/v1/logs, but the SDK does not use it: replay is off, and console capture is emitted as spans. The UI server forwards traces to OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and logs to OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, using OTEL_EXPORTER_OTLP_HEADERS. When the traces endpoint is unset, the browser SDK does not start. A signal whose endpoint is unset returns 204.

Advanced

Railway

ctx| can be deployed on Railway with prebuilt images from GitHub Container Registry. A typical flow is:

1. Build and push service images from CI:
   • ghcr.io/ctxpipe-ai/backend:<sha>
   • ghcr.io/ctxpipe-ai/worker:<sha>
   • ghcr.io/ctxpipe-ai/ui:<sha>
   • ghcr.io/ctxpipe-ai/codesearch:<sha>
2. Configure Railway services to use image sources.
3. Set environment variables and secrets in Railway.
4. Roll production by changing service image tags to the intended commit SHA.

Related pages