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, OTEL collector, migrator, backend, worker, UI, and codesearch. 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 uses a deployment-owned OAuth application and signed application webhooks. Put the credentials on both backend and worker services.

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.

Observability

ctx| can export OpenTelemetry data when endpoints are configured.

The repo includes a reference OpenTelemetry Collector in apps/otel-collector that can fan out to APM and Langfuse-style trace backends.

Advanced

Amplitude configuration is read by the UI at runtime. Changing it does not require rebuilding the UI image. Leave AMPLITUDE_API_KEY unset to disable product analytics.

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