Installation Overview

Installing the Contexa CLI and initializing a Spring project are separate steps. contexa init offers a ready-to-run Quick setup and a choice-driven Custom setup; manual dependency-only integration remains a separate path.

Prerequisites

Before installing Contexa, ensure your environment meets the following requirements:

Requirement Minimum Version Notes
Java 17+ LTS release (17)
Spring Boot 3.5.4 Managed by the starter BOM (Jakarta EE namespace)
Spring Security 6.2+ Included transitively via Spring Boot Starter
Docker Conditional Supported release Required when the CLI starts Compose services; not required with --no-docker
PostgreSQL CLI-managed or external 15+ Quick generates a dedicated service; prepare it externally for the Custom external-infrastructure path
Redis Distributed only 7.0+ Distributed mode only — required for shared caching and event streaming

LLM requirement — Quick selects one provider and defaults to local Ollama. Custom accepts one or more providers. Manual dependency-only integration requires no LLM configuration.

Manual dependency-only — If you add only the Starter and do not use @EnableAISecurity, Contexa does not participate in host security. This is not the Quick default. The CLI does not create product tables; the activated OSS or Enterprise runtime creates and validates its own schema during server startup.

Module Architecture

Contexa is composed of modular layers, each responsible for a distinct security domain. The Spring Boot Starter aggregates all modules into a single dependency.

Module Artifact Responsibility
Starter spring-boot-starter-contexa Aggregator dependency; provides all modules while loading security configuration only when activation conditions match
Common contexa-common Shared annotations (@EnableAISecurity, @Protectable), enums, entity models, and cache abstractions
Core contexa-core AI pipeline, LLM orchestration, HCAD engine, Zero Trust evaluation, RAG and vector store integration
Identity contexa-identity Identity DSL, authentication flows (form, REST, OTT, passkey), adaptive MFA, session management
IAM contexa-iam XACML policy engine, @Protectable method interception, dynamic authorization, admin dashboard
Auto-Configure contexa-autoconfigure Spring Boot auto-configuration for all modules; conditional bean registration based on classpath and properties

Infrastructure Modes

Quick selects Standalone infrastructure and generates PostgreSQL plus Ollama when Ollama is selected. Custom lets you select Standalone, Distributed, or Skip.

Standalone infrastructure

Generates a project-owned Compose file for PostgreSQL and the selected Ollama service. Quick starts it when Docker is available; --no-docker generates files without starting containers.

Distributed Mode

Select it explicitly in Custom or with --distributed. It configures PostgreSQL, Redis, ZooKeeper, Kafka, and the selected Ollama service.

Installation Pathways

Choose the path that best fits your needs:

Get Started

Follow Quick or Custom initialization, selection-driven code, configuration, and infrastructure generation, and reset.

Spring Boot Integration

Deep dive into the Identity DSL, security configuration, and authentication flow composition.

Configuration Reference

Complete property reference for all Contexa modules, including Zero Trust, HCAD, and LLM settings.

Shadow Mode Migration

Safely adopt AI-driven security with the 2-stage security.zerotrust.mode migration path (SHADOW → ENFORCE).

Dependency Coordinates

Stable artifacts are published to Maven Central under the ai.ctxa group. Use the single Starter as the entry point; stable releases need no milestone or snapshot repository beyond mavenCentral().

Gradle (Kotlin DSL) 
implementation("ai.ctxa:spring-boot-starter-contexa:0.1.0")
Maven 
<dependency>
    <groupId>ai.ctxa</groupId>
    <artifactId>spring-boot-starter-contexa</artifactId>
    <version>0.1.0</version>
</dependency>