Infrastructure Configuration

Enable distributed mode (PoC / enterprise demo) — Run contexa init --distributed and the CLI will:

Dependencies — automatically add spring-kafka and redisson to your build file.
Infrastructure — generate a docker-compose.yml with PostgreSQL + Ollama + Redis + Kafka + Zookeeper.
Configuration — set contexa.infrastructure.mode: DISTRIBUTED and the Redis / Kafka hosts inside the Contexa-managed block of application.yml.

The properties on this page apply once distributed mode is enabled. For production, use Kubernetes + Helm.

Contexa Core Properties (Summary)

The top-level ContexaProperties class (prefix contexa) contains the master switches for infrastructure mode, Redis, Kafka, and observability. These properties are fully documented on the Configuration Overview page. Key infrastructure-related entries include:

Property	Type	Default	Description
`contexa` (master)
`contexa.enabled`	`boolean`	`true`	Top-level master switch for the entire Contexa auto-configuration. When `false`, every sub-module is disabled.
`contexa.infrastructure`
`.mode`	`enum`	`STANDALONE`	`STANDALONE` (in-memory) or `DISTRIBUTED` (Redis/Kafka)
`.redis.enabled`	`boolean`	`true`	Enable Redis for distributed caching and pub/sub
`.kafka.enabled`	`boolean`	`true`	Enable Kafka for event streaming in distributed mode
`.observability.enabled`	`boolean`	`true`	Enable observability infrastructure
`.observability.open-telemetry-enabled`	`boolean`	`true`	Enable OpenTelemetry for distributed tracing

See the Configuration Overview for the complete ContexaProperties reference.

Cache Properties

Properties under contexa.cache, bound to ContexaCacheProperties. Controls the multi-tier caching subsystem used throughout Contexa for identity, policy, and behavioral data. Supports local (Caffeine), Redis, and hybrid caching strategies with optional pub/sub-based cache invalidation.

General Settings

Property	Type	Default	Description
`contexa.cache`
`.type`	`CacheType`	`REDIS`	`LOCAL`, `REDIS`, or `HYBRID` (L1 local + L2 Redis)
`.local.max-size`	`int`	`1000`	Max entries in the local (L1) cache
`.local.default-ttl-seconds`	`int`	`60`	Default TTL (seconds) for local cache entries
`.redis.default-ttl-seconds`	`int`	`300`	Default TTL (seconds) for Redis cache entries
`.redis.key-prefix`	`String`	`contexa:cache:`	Prefix for all Redis cache keys (namespace isolation)
`.pubsub.enabled`	`boolean`	`true`	Enable pub/sub cache invalidation across cluster nodes
`.pubsub.channel`	`String`	`contexa:cache:invalidation`	Pub/sub channel for cache invalidation broadcasts

Domain-Specific TTL

Each cache domain can have independent TTL values for local and Redis tiers. This allows fine-grained control — for example, frequently changing policy data can use shorter TTLs while stable HCAD baseline data uses longer ones.

Property	Type	Default	Description
`contexa.cache.domains`
`.users`	`TtlConfig`	`local: 3600 / redis: 3600`	User identity and profile data
`.roles`	`TtlConfig`	`local: 14400 / redis: 14400`	Role definitions and permission mappings
`.permissions`	`TtlConfig`	`local: 28800 / redis: 28800`	Permission grants and access control entries
`.groups`	`TtlConfig`	`local: 14400 / redis: 14400`	Group membership and hierarchy data
`.policies`	`TtlConfig`	`local: 30 / redis: 300`	XACML/ABAC policy definitions (short local TTL)
`.soar`	`TtlConfig`	`local: 900 / redis: 900`	SOAR playbook and automated response data
`.hcad`	`TtlConfig`	`local: 86400 / redis: 86400`	HCAD behavioral baselines (long-lived profiles)

Each domain entry is a TtlConfig object with local-ttl-seconds and redis-ttl-seconds fields. Override any domain independently:

YAML

contexa:
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "myapp:contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 60
      hcad:
        local-ttl-seconds: 43200
        redis-ttl-seconds: 86400

Security Kafka Properties

Properties under security.kafka, bound to SecurityKafkaProperties. Configures Kafka topic names for Contexa's security event pipeline.

Property	Type	Default	Description
`security.kafka.topic` (TopicSettings)
`.authorization`	`String`	`security-authorization-events`	Authorization-decision event topic.
`.authentication`	`String`	`auth-events`	Authentication event topic.
`.incident`	`String`	`security-incident-events`	Security-incident event topic.
`.threat`	`String`	`threat-indicators`	Threat-indicators topic.
`.audit`	`String`	`security-audit-events`	Audit-event topic.
`.general`	`String`	`security-events`	General security-event topic.
`.dlq`	`String`	`security-events-dlq`	Dead-letter queue topic for failed event processing.
`.soar-action`	`String`	`soar-action-events`	SOAR action event topic.
`security.kafka.dlq` (DlqSettings)
`.max-retries`	`int`	`3`	Maximum DLQ processing retries.
`.retry-delay-ms`	`int`	`5000`	Delay between retries in milliseconds.
`.alert-threshold`	`int`	`10`	Alerting threshold for the number of DLQ messages.

YAML

security:
  kafka:
    topic:
      authorization: security-authorization-events
      authentication: auth-events
      incident: security-incident-events
      threat: threat-indicators
      audit: security-audit-events
      general: security-events
      dlq: security-events-dlq
      soar-action: soar-action-events
    dlq:
      max-retries: 3
      retry-delay-ms: 5000
      alert-threshold: 10

OpenTelemetry Properties

Properties under contexa.opentelemetry, bound to OpenTelemetryProperties. Configures the OpenTelemetry integration for distributed tracing, metrics export, and observability.

Property	Type	Default	Description
`contexa.opentelemetry`
`.enabled`	`boolean`	`true`	Enable OpenTelemetry trace and metric export
`.service-name`	`String`	`contexa-core`	Service name in trace spans and metric labels
`.exporter-endpoint`	`String`	`http://localhost:4317`	OTLP exporter endpoint (gRPC; 4318 for HTTP)
`.sampling-probability`	`double`	`1.0`	Sampling probability (0.0–1.0); lower in production

YAML

contexa:
  opentelemetry:
    enabled: true
    service-name: "my-application"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

Security Redis Properties

Properties under security.redis, bound to SecurityRedisProperties. Configures Redis pub/sub channel names, Redis stream keys, TTL, and memory thresholds for Contexa's security events.

Property	Type	Default	Description
`security.redis.channel` (ChannelSettings)
`.authorization`	`String`	`security:authorization:events`	Authorization-event pub/sub channel.
`.authentication`	`String`	`security:events`	Authentication-event pub/sub channel.
`.incident`	`String`	`security:incidents`	Incident pub/sub channel.
`.threat`	`String`	`security:threats`	Threat pub/sub channel.
`.audit`	`String`	`security:audit:events`	Audit pub/sub channel.
`.general`	`String`	`security:events`	General pub/sub channel.
`security.redis.stream` (StreamSettings)
`.authorization`	`String`	`security:stream:authorization`	Authorization Redis stream key.
`.incident`	`String`	`security:stream:incident`	Incident Redis stream key.
`.threat`	`String`	`security:stream:threat`	Threat Redis stream key.
`.audit`	`String`	`security:stream:audit`	Audit Redis stream key.
`.general`	`String`	`security:stream:general`	General Redis stream key.
`.authentication`	`String`	`security:stream:authentication`	Authentication Redis stream key.
`.maxlen`	`int`	`10000`	Maximum entries per Redis stream (XADD MAXLEN).
`security.redis.ttl` (TtlSettings)
`.minutes`	`int`	`60`	Default Redis TTL for event data (minutes).
`security.redis.memory` (MemorySettings)
`.max-mb`	`int`	`1024`	Memory cap (MB) Contexa security events may consume in Redis.
`.warning-threshold`	`double`	`0.8`	Warning threshold for memory usage (0.0-1.0).
`.critical-threshold`	`double`	`0.9`	Critical threshold for memory usage (0.0-1.0).

Scheduler Lock Properties

Properties under contexa.scheduler.lock, bound to ContexaSchedulerLockProperties (record). Controls the ShedLock auto-configuration that ensures single execution of @Scheduled + @SchedulerLock methods across multiple JVMs. Single-instance deployments may keep the defaults — locks always succeed and the overhead is negligible.

Property	Type	Default	Description
`contexa.scheduler.lock`
`.enabled`	`boolean`	`true`	Whether the ShedLock auto-configuration registers a `LockProvider` bean. Setting this to `false` disables every `@SchedulerLock`; each `@Scheduled` method then reverts to single-JVM-only exclusivity.
`.default-lock-at-most-for`	`Duration`	`5m`	Fallback upper bound applied when a specific scheduler omits `lockAtMostFor`. Prevents stuck locks from surviving indefinitely after a JVM crash.
`.use-database-time`	`boolean`	`true`	When `true`, the `JdbcTemplateLockProvider` uses `now()` from the database engine so every instance sees the same clock. When `false`, it falls back to the JVM clock (useful for local H2 tests with a misaligned timezone).

DataSource Properties

Properties under contexa.datasource, bound to ContexaDataSourceProperties. Defines the database connection Contexa uses for its own metadata (policies, users, audit log, etc.). Can be isolated from the host application's spring.datasource.

Property	Type	Default	Description
`contexa.datasource`
`.url`	`String`	`null`	JDBC URL. When empty, the host application's `spring.datasource.url` may be reused depending on the isolation policy.
`.username`	`String`	`null`	Database username.
`.password`	`String`	`null`	Database password.
`.driver-class-name`	`String`	`null`	JDBC driver class name. When empty, derived from the URL automatically.
`contexa.datasource.isolation` (Isolation)
`.allow-shared-application-datasource`	`boolean`	`false`	Allows reusing the host application's datasource. Default is isolation (separate connection pool).
`.shared-application-datasource-risk-accepted`	`boolean`	`false`	Operator's explicit acknowledgment of the risk of using a shared datasource.
`.contexa-owned-application`	`boolean`	`false`	Indicates that the application itself is operated by Contexa (bypasses isolation validation).

Full Configuration Example

A production-ready application.yml combining all infrastructure properties for a distributed deployment with Redis, Kafka, and an external OpenTelemetry collector.

YAML

# Infrastructure configuration for Contexa distributed deployment
contexa:
  enabled: true
  infrastructure:
    mode: DISTRIBUTED
    redis:
      enabled: true
    kafka:
      enabled: true
    observability:
      enabled: true
      open-telemetry-enabled: true

  # Multi-tier caching
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      roles:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      permissions:
        local-ttl-seconds: 14400
        redis-ttl-seconds: 28800
      groups:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 120
      soar:
        local-ttl-seconds: 900
        redis-ttl-seconds: 900
      hcad:
        local-ttl-seconds: 86400
        redis-ttl-seconds: 86400

  # OpenTelemetry
  opentelemetry:
    enabled: true
    service-name: "contexa-production"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

# Security event infrastructure - Kafka
security:
  kafka:
    topic:
      dlq: "security-events-dlq"