Configuration Reference¶

All backend configuration is loaded from TOML files — no environment variables, no .env files. The Settings class (app/settings.py) reads files in this order, each layer overriding the previous:

config.toml — base settings, committed to git (no secrets)
secrets.toml — sensitive values (SECRET_KEY, MONGODB_URL), gitignored
per-worker override — optional TOML file for service-specific settings (e.g. config.coordinator.toml)

# Default — reads config.toml + secrets.toml
Settings()

# Tests — reads config.test.toml + secrets.toml
Settings(config_path="config.test.toml")

# Worker — reads config.toml + secrets.toml + worker override
Settings(override_path="config.coordinator.toml")

Secrets¶

Credentials live in secrets.toml, which is gitignored. A committed template with development defaults is provided:

cp backend/secrets.example.toml backend/secrets.toml

# Copy to secrets.toml and fill in real values.
#   cp secrets.example.toml secrets.toml
#
# Required keys (no defaults in config.toml):
#   SECRET_KEY   — JWT signing key, min 32 characters
#   MONGODB_URL  — full connection string with credentials
#
# GitHub Actions: create secrets.toml from repository secrets:
#   cat > backend/secrets.toml << EOF
#   SECRET_KEY = "${{ secrets.JWT_SECRET_KEY }}"
#   MONGODB_URL = "${{ secrets.MONGODB_URL }}"
#   EOF
#
# Kubernetes: store as a Secret and mount at /app/secrets.toml

SECRET_KEY = "CHANGE_ME_min_32_chars_long_!!!!"
MONGODB_URL = "mongodb://root:rootpassword@mongo:27017/integr8scode?authSource=admin"

For production, mount secrets.toml from a Kubernetes Secret at /app/secrets.toml. In CI, generate it from repository secrets (see the template comments for an example).

Core¶

# Integr8sCode backend configuration (development defaults).
# Secrets (SECRET_KEY, MONGODB_URL credentials) live in secrets.toml (gitignored).
# Production: mount secrets.toml from a Kubernetes Secret or generate in CI.
# See secrets.example.toml for the required keys.

PROJECT_NAME = "integr8scode"
DATABASE_NAME = "integr8scode_db"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 1440

Legend

Key	Description	Default
`PROJECT_NAME`	Application name for logs and metadata	`integr8scode`
`DATABASE_NAME`	MongoDB database name	`integr8scode_db`
`SECRET_KEY`	JWT signing key, min 32 chars. Lives in `secrets.toml`	— (required)
`ALGORITHM`	JWT signing algorithm	`HS256`
`ACCESS_TOKEN_EXPIRE_MINUTES`	Token lifetime in minutes	`1440` (24h)
`MONGODB_URL`	MongoDB connection string. Lives in `secrets.toml`	`mongodb://mongo:27017/integr8scode`

Kubernetes¶

MONGODB_URL = "mongodb://mongo:27017/integr8scode"

KUBERNETES_CONFIG_PATH = "/app/kubeconfig.yaml"
KUBERNETES_CA_CERTIFICATE_PATH = "/app/certs/k8s-ca.pem"
K8S_POD_CPU_LIMIT = "1000m"
K8S_POD_MEMORY_LIMIT = "128Mi"
K8S_POD_CPU_REQUEST = "200m"
K8S_POD_MEMORY_REQUEST = "128Mi"
K8S_POD_EXECUTION_TIMEOUT = 5
K8S_NAMESPACE = "integr8scode"

Legend

Key	Description	Default
`KUBERNETES_CONFIG_PATH`	Path to kubeconfig	`~/.kube/config`
`KUBERNETES_CA_CERTIFICATE_PATH`	Custom CA cert for K8s API	—
`K8S_POD_CPU_LIMIT`	CPU limit per pod	`1000m`
`K8S_POD_MEMORY_LIMIT`	Memory limit per pod	`128Mi`
`K8S_POD_CPU_REQUEST`	CPU request (guaranteed)	`1000m`
`K8S_POD_MEMORY_REQUEST`	Memory request (guaranteed)	`128Mi`
`K8S_POD_EXECUTION_TIMEOUT`	Max execution time in seconds	`300`
`K8S_NAMESPACE`	Namespace for executor pods	`integr8scode`
`RATE_LIMITS`	Default rate limit string	`100/minute`

Kafka¶

# Kafka
KAFKA_BOOTSTRAP_SERVERS = "kafka:29092"
ENABLE_EVENT_STREAMING = true
EVENT_RETENTION_DAYS = 30
KAFKA_CONSUMER_GROUP_ID = "integr8scode-backend"
KAFKA_AUTO_OFFSET_RESET = "earliest"
KAFKA_ENABLE_AUTO_COMMIT = true
KAFKA_SESSION_TIMEOUT_MS = 45000
KAFKA_HEARTBEAT_INTERVAL_MS = 10000
KAFKA_REQUEST_TIMEOUT_MS = 40000
KAFKA_MAX_POLL_RECORDS = 500

Legend

Key	Description	Default
`KAFKA_BOOTSTRAP_SERVERS`	Broker addresses (comma-separated)	`kafka:29092`
`ENABLE_EVENT_STREAMING`	Enable Kafka events	`false`
`EVENT_RETENTION_DAYS`	Days to retain events in MongoDB	`30`
`KAFKA_CONSUMER_GROUP_ID`	Consumer group ID	`integr8scode-backend`
`KAFKA_AUTO_OFFSET_RESET`	Where to start if no offset	`earliest`
`KAFKA_ENABLE_AUTO_COMMIT`	Auto-commit offsets	`true`
`KAFKA_SESSION_TIMEOUT_MS`	Session timeout before rebalance	`45000`
`KAFKA_HEARTBEAT_INTERVAL_MS`	Heartbeat frequency	`10000`
`KAFKA_REQUEST_TIMEOUT_MS`	Broker request timeout	`40000`
`KAFKA_MAX_POLL_RECORDS`	Max records per poll	`500`

SSE (Server-Sent Events)¶

SSE_CONSUMER_POOL_SIZE = 10
SSE_HEARTBEAT_INTERVAL = 30

Legend

Key	Description	Default
`SSE_CONSUMER_POOL_SIZE`	Number of Kafka consumers for SSE streaming	`10`
`SSE_HEARTBEAT_INTERVAL`	Keepalive interval in seconds	`30`

Tracing (OpenTelemetry)¶

ENABLE_TRACING = true
JAEGER_AGENT_HOST = "jaeger"
JAEGER_AGENT_PORT = 6831
TRACING_SERVICE_NAME = "integr8scode-backend"
TRACING_SERVICE_VERSION = "1.0.0"
TRACING_SAMPLING_RATE = 1.0

Legend

Key	Description	Default
`ENABLE_TRACING`	Enable distributed tracing	`true`
`JAEGER_AGENT_HOST`	Jaeger agent hostname	`jaeger`
`JAEGER_AGENT_PORT`	Jaeger agent UDP port	`6831`
`TRACING_SERVICE_NAME`	Service name in traces	`integr8scode-backend`
`TRACING_SERVICE_VERSION`	Version in trace metadata	`1.0.0`
`TRACING_SAMPLING_RATE`	Sample rate (0.0-1.0)	`0.1`

Dead Letter Queue¶

DLQ_RETRY_MAX_ATTEMPTS = 5
DLQ_RETRY_BASE_DELAY_SECONDS = 60.0
DLQ_RETRY_MAX_DELAY_SECONDS = 3600.0
DLQ_RETENTION_DAYS = 7
DLQ_WARNING_THRESHOLD = 100
DLQ_CRITICAL_THRESHOLD = 1000

Legend

Key	Description	Default
`DLQ_RETRY_MAX_ATTEMPTS`	Retries before archiving	`5`
`DLQ_RETRY_BASE_DELAY_SECONDS`	Base delay between retries	`60`
`DLQ_RETRY_MAX_DELAY_SECONDS`	Max delay (backoff cap)	`3600`
`DLQ_RETENTION_DAYS`	Days to keep DLQ messages	`7`
`DLQ_WARNING_THRESHOLD`	Warning alert threshold	`100`
`DLQ_CRITICAL_THRESHOLD`	Critical alert threshold	`1000`

Service & OTEL¶

SERVICE_NAME = "integr8scode-backend"
SERVICE_VERSION = "1.0.0"

# OpenTelemetry
OTEL_EXPORTER_OTLP_ENDPOINT = "http://otel-collector:4317"
OTEL_SERVICE_NAME = "integr8scode-backend"
OTEL_SERVICE_VERSION = "1.0.0"
OTEL_RESOURCE_ATTRIBUTES = "environment=production,team=backend"

Legend

Key	Description	Default
`APP_URL`	Public URL for notifications	`https://integr8scode.cc`
`SERVICE_NAME`	Service identifier	`integr8scode-backend`
`SERVICE_VERSION`	Service version	`1.0.0`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint	—
`OTEL_SERVICE_NAME`	OTEL service name	—
`OTEL_SERVICE_VERSION`	OTEL service version	—
`OTEL_RESOURCE_ATTRIBUTES`	Additional resource attributes	—

Server¶

WEB_CONCURRENCY = 4
WEB_THREADS = 4
WEB_TIMEOUT = 60
WEB_BACKLOG = 2048

BCRYPT_ROUNDS = 12
REDIS_MAX_CONNECTIONS = 200

Legend

Key	Description	Default
`WEB_CONCURRENCY`	Gunicorn worker processes	`4`
`WEB_THREADS`	Threads per worker	`1`
`WEB_TIMEOUT`	Request timeout in seconds	`60`
`WEB_BACKLOG`	TCP connection backlog	`2048`
`SERVER_HOST`	Bind address	`localhost`
`BCRYPT_ROUNDS`	Password hashing rounds	`12`
`REDIS_MAX_CONNECTIONS`	Redis connection pool size	`200`

Worker overrides¶

Each worker runs with a small override TOML that sets TRACING_SERVICE_NAME and KAFKA_CONSUMER_GROUP_ID. These are mounted alongside config.toml and secrets.toml in Docker Compose:

File	Service
`config.coordinator.toml`	Execution coordinator
`config.k8s-worker.toml`	Kubernetes pod manager
`config.pod-monitor.toml`	Pod status watcher
`config.result-processor.toml`	Result processor
`config.saga-orchestrator.toml`	Saga orchestrator
`config.event-replay.toml`	Event replay
`config.dlq-processor.toml`	Dead letter queue processor

Test configuration¶

config.test.toml is a full config file tuned for fast test execution (lower bcrypt rounds, relaxed rate limits, shorter Kafka timeouts). Tests load it with:

Settings(config_path="config.test.toml")

Secrets are still loaded from secrets.toml. In CI, the workflow copies the example template:

cp backend/secrets.example.toml backend/secrets.toml