Environment Variables
All Causet services are configured through environment variables. This page documents the variables for each service. The canonical production reference is ecs-env-vars-reference.md in the repository root.
causet-runtime-service
The runtime service processes intents, evaluates rules, and writes events to the ledger.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | Yes | — | R2DBC URL for the causet database. Format: r2dbc:postgresql://host:5432/causet |
KAFKA_BOOTSTRAP_SERVERS | Yes | — | Comma-separated Kafka broker addresses |
S3_ENDPOINT | Yes | — | S3-compatible endpoint URL. Use https://s3.amazonaws.com for AWS, MinIO URL for local |
S3_BUCKET | Yes | — | Bucket name for IR artifacts (e.g., causet-artifacts-prod) |
AWS_ACCESS_KEY_ID | Yes | — | AWS/MinIO access key for S3 access |
AWS_SECRET_ACCESS_KEY | Yes | — | AWS/MinIO secret key for S3 access |
AWS_REGION | No | us-east-1 | AWS region for S3 |
CAUSET_SAAS_URL | Yes | — | Internal URL of causet-saas-cloud for release resolution |
SERVER_PORT | No | 8080 | HTTP server port |
GRPC_PORT | No | 9090 | gRPC server port |
SPRING_PROFILES_ACTIVE | No | default | Spring profile. Set to prod for production configuration |
JAVA_OPTS | No | — | JVM options. Example: -Xms512m -Xmx1536m |
REDIS_URL | No | — | Redis URL for IR artifact caching. If unset, artifacts are fetched from S3 on each load |
CAUSET_OPENAI_API_KEY | No | — | Platform OpenAI key for AI decisions and embeddings (fallback when no BYOK) |
OPENAI_API_KEY | No | — | Alias for CAUSET_OPENAI_API_KEY |
CAUSET_SECRETS_MASTER_KEY | No | — | AES-256-GCM master key for decrypting BYOK provider keys from control plane |
CAUSET_MEMORY_STORE | No | in-memory | Memory backend: in-memory or postgres |
CAUSET_MEMORY_INGESTION_ENABLED | No | false | When true, embed source events into vector memory |
CAUSET_MEMORY_RETRIEVAL_LIMIT | No | 10 | Max memory snippets retrieved per decision memory ref |
WEBHOOK_DELIVERY_ENABLED | No | true | Set false when ws-gateway handles webhook delivery |
WEBHOOK_EMIT_IN_DRY_RUN | No | true | Emit ledger/intent webhooks from DRY_RUN forks when true |
causet-projection-worker
The projection worker consumes events from Kafka and UPSERTs into projection tables.
| Variable | Required | Default | Description |
|---|---|---|---|
PROJECTIONS_DB_URL | Yes | — | JDBC URL for the projections database. Format: jdbc:postgresql://host:5432/projections |
KAFKA_BOOTSTRAP_SERVERS | Yes | — | Comma-separated Kafka broker addresses |
KAFKA_GROUP_ID | No | causet-projection-worker | Kafka consumer group ID |
S3_ENDPOINT | Yes | — | S3-compatible endpoint URL |
S3_BUCKET | Yes | — | Bucket name for IR artifacts |
AWS_ACCESS_KEY_ID | Yes | — | AWS/MinIO access key |
AWS_SECRET_ACCESS_KEY | Yes | — | AWS/MinIO secret key |
AWS_REGION | No | us-east-1 | AWS region |
CAUSET_SAAS_URL | Yes | — | Internal URL of causet-saas-cloud for active release resolution |
WORKER_HEALTH_PORT | No | 8083 | Internal HTTP port for /actuator/health |
DLQ_TOPIC | No | causet.projection-dlq.v1 | Dead-letter queue topic name |
MAX_RETRY_ATTEMPTS | No | 3 | Maximum retry attempts before sending to DLQ |
RETRY_BACKOFF_MS | No | 1000 | Initial retry backoff in milliseconds (exponential) |
JAVA_OPTS | No | — | JVM options |
causet-query-service
The query service executes named queries against projection tables.
| Variable | Required | Default | Description |
|---|---|---|---|
PROJECTIONS_DB_URL | Yes | — | JDBC or R2DBC URL for the projections database |
REDIS_URL | No | — | Redis URL for query result caching. Leave unset to disable caching |
REDIS_CACHE_TTL_SECONDS | No | 30 | Query result cache TTL in seconds |
S3_ENDPOINT | Yes | — | S3-compatible endpoint URL |
S3_BUCKET | Yes | — | Bucket name for IR artifacts |
AWS_ACCESS_KEY_ID | Yes | — | AWS/MinIO access key |
AWS_SECRET_ACCESS_KEY | Yes | — | AWS/MinIO secret key |
AWS_REGION | No | us-east-1 | AWS region |
CAUSET_SAAS_URL | Yes | — | Internal URL of causet-saas-cloud for active release resolution |
SERVER_PORT | No | 8082 | HTTP server port |
JAVA_OPTS | No | — | JVM options |
causet-saas-cloud
The SaaS / control plane API manages platforms, applications, releases, and fork deployments.
| Variable | Required | Default | Description |
|---|---|---|---|
CONTROL_PLANE_DB_URL | Yes | — | JDBC URL for the control plane database (causet_control_plane) |
CLERK_SECRET_KEY | Yes | — | Clerk secret key for JWT verification |
CLERK_PUBLISHABLE_KEY | Yes | — | Clerk publishable key |
S3_ENDPOINT | Yes | — | S3-compatible endpoint URL |
S3_BUCKET | Yes | — | Bucket name for IR artifact storage |
AWS_ACCESS_KEY_ID | Yes | — | AWS/MinIO access key (needs s3:PutObject for uploads) |
AWS_SECRET_ACCESS_KEY | Yes | — | AWS/MinIO secret key |
AWS_REGION | No | us-east-1 | AWS region |
SERVER_PORT | No | 8085 | HTTP server port |
JAVA_OPTS | No | — | JVM options |
CAUSET_SECRETS_MASTER_KEY | No | — | AES key for BYOK AI provider secrets (must match runtime) |
causet-cloud-control-plane
The Next.js web UI for the control plane.
| Variable | Required | Default | Description |
|---|---|---|---|
NEXT_PUBLIC_CAUSET_SAAS_URL | Yes | — | Public URL of causet-saas-cloud (accessed from the browser) |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Yes | — | Clerk publishable key for frontend auth |
CLERK_SECRET_KEY | Yes | — | Clerk secret key for server-side auth |
PORT | No | 3000 | Next.js server port |
ws-gateway-go
The WebSocket gateway proxies real-time event streams to connected clients.
| Variable | Required | Default | Description |
|---|---|---|---|
KAFKA_BOOTSTRAP_SERVERS | Yes | — | Comma-separated Kafka broker addresses |
KAFKA_GROUP_ID | No | ws-gateway | Kafka consumer group ID |
PORT | No | 8081 | WebSocket server port |
CAUSET_SAAS_URL | Yes | — | Internal URL of causet-saas-cloud for auth token validation |
CAUSET_SECRETS_MASTER_KEY | No | — | Decrypt webhook signing secrets synced from saas-cloud |
Secrets management
In production, do not place sensitive values directly in ECS task definitions. Use AWS Secrets Manager and reference secrets by ARN:
"secrets": [
{
"name": "DATABASE_URL",
"valueFrom": "arn:aws:secretsmanager:us-east-1:ACCOUNT:secret:causet/prod/runtime-db-url"
},
{
"name": "CLERK_SECRET_KEY",
"valueFrom": "arn:aws:secretsmanager:us-east-1:ACCOUNT:secret:causet/prod/clerk-secret-key"
}
]ECS injects the secret value as an environment variable at container startup. Secrets Manager supports automatic rotation for RDS credentials with the built-in rotation lambda.
See Secrets Management for more detail.
Local vs production differences
| Setting | Local (Docker Compose) | Production (AWS) |
|---|---|---|
S3_ENDPOINT | http://minio:9000 | https://s3.amazonaws.com (or omit to use default) |
DATABASE_URL | r2dbc:postgresql://postgres:5432/causet | RDS endpoint |
PROJECTIONS_DB_URL | jdbc:postgresql://postgres:5432/projections | RDS endpoint |
KAFKA_BOOTSTRAP_SERVERS | redpanda:9092 | MSK broker endpoints |
REDIS_URL | redis://redis:6379 | ElastiCache endpoint |
AWS_ACCESS_KEY_ID | minioadmin | IAM role (no key needed with task role) |
| Secrets management | .env files | AWS Secrets Manager |
Note: On AWS ECS with a task role configured, you do not need
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYfor S3 access. The AWS SDK automatically uses the task role credentials. Only set these explicitly when using MinIO or a non-AWS S3-compatible store.