Installation Guide

Quick Install (Recommended)

Install the Contexa CLI and set up everything automatically with a single command.

Step 1 - Install CLI

curl -fsSL https://install.ctxa.ai | sh

irm https://install.ctxa.ai/install.ps1 | iex

Step 2 - Initialize your project

Before running the full setup, you can test if your environment meets all requirements by executing the pre-flight check:

contexa init --check

Once checks pass successfully, proceed with the interactive project setup:

cd your-spring-project
contexa init

Upon starting, a Pre-installation diagnostic runs automatically. If any Docker daemon issues or Java version conflicts are detected, helpful instructions are displayed. You can also manually invoke contexa doctor to run a complete diagnostic scan.

The CLI will guide you through an interactive setup:

• Project type - New project (FULL) or legacy system (SANDBOX)
• AI security mode - Monitor only or block threats immediately
• AI / LLM Model - Ollama (local), OpenAI, or Anthropic
• Infrastructure - Standard (PostgreSQL + Ollama, single-server in-memory) by default. PoC / enterprise demo with Redis + Kafka can be enabled via contexa init --distributed

The CLI automatically:

• Adds spring-boot-starter-contexa dependency to your build file
• Configures application.yml with the correct settings
• Generates docker-compose.yml for infrastructure
• Starts Docker containers and pulls AI models

Step 3 - Add annotations

@EnableAISecurity
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

// Protect any endpoint with AI Zero Trust
@Protectable
@GetMapping("/api/customers")
public List<Customer> getCustomers() { ... }

Step 4 - Start your application

./gradlew bootRun

Legacy System Integration (SANDBOX Mode)

If your project already has its own authentication system, use SANDBOX mode. Contexa adds AI security on top of your existing login — without modifying it.

@EnableAISecurity(
    mode = SecurityMode.SANDBOX,
    authObjectLocation = AuthObjectLocation.SESSION,
    authObjectAttribute = "loginUser"  // your legacy session attribute name
)
@SpringBootApplication
public class LegacyApplication { }

Contexa CLI Command Reference

Detailed overview of the primary commands provided by the Contexa CLI. You can execute them in your terminal via contexa <command> [options].

Prerequisites

Required for both CLI and manual installation:

Manual Installation

If you prefer not to use the CLI, follow these steps manually.

1. Add Dependency

dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
}

<dependency>
    <groupId>ai.ctxa</groupId>
    <artifactId>spring-boot-starter-contexa</artifactId>
    <version>0.1.0</version>
</dependency>

2. Start Infrastructure

# Standard mode (PostgreSQL + Ollama)
docker compose up -d

# Pull AI models
docker exec contexa-ollama ollama pull qwen2.5:14b
docker exec contexa-ollama ollama pull mxbai-embed-large

# Distributed mode for PoC/enterprise demo (PostgreSQL + Ollama + Redis + Kafka)
# Run `contexa init --distributed` so docker-compose.yml includes Redis & Kafka.
docker compose up -d

3. Infrastructure Services

Troubleshooting

@EnableAISecurity startup error guide

If you went through the manual install (added only spring-boot-starter-contexa and declared @EnableAISecurity), you may hit the following three errors in sequence at startup. The only dependency contexa-cli auto-injects is spring-boot-starter-contexa; the rest must be added by you. Each error below shows the exact message, root cause, and fix.

Error 1 — contexa.datasource.url must be configured for @EnableAISecurity

Root cause — Contexa stores security policy, sessions and the vector index in a dedicated PostgreSQL instance, isolated from your application database. When @EnableAISecurity is on, contexa.datasource.url must be set or ContexaDataSourceIsolation fails fast.

Fix — add a Contexa-owned datasource block to your application.yml:

contexa:
  datasource:
    url: jdbc:postgresql://localhost:5432/contexa
    username: ${CONTEXA_DB_USERNAME:contexa}
    password: ${CONTEXA_DB_PASSWORD:contexa1234!@#}
    driver-class-name: org.postgresql.Driver
    isolation:
      contexa-owned-application: true

You may share the application's PostgreSQL instance via a separate schema if your operations team explicitly approves it. The default is a separate database (recommended).

Error 2 — No Spring AI ChatModel is configured for CONTEXA

Root cause — Contexa's tiered LLM auto-configuration (CoreLLMTieredAutoConfiguration) requires a ChatModel bean, but no Spring AI provider starter is on the classpath. spring-boot-starter-contexa intentionally does not pull a ChatModel starter as a transitive dependency — the choice of provider (Ollama / OpenAI / Anthropic) is yours.

Fix — add at least one provider starter to your build and configure the matching contexa.llm.* block (Contexa bypasses Spring AI's default autoconfiguration and manages model creation via its dedicated contexa.llm namespace):

dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
    // Add only when you declare @EnableAISecurity (one provider or more)
    implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}

contexa:
  llm:
    selection:
      chat:
        mode: dynamic-priority
        priority: ollama,openai,anthropic
    chat:
      ollama:
        baseUrl: ${CONTEXA_CHAT_OLLAMA_BASE_URL:http://127.0.0.1:11434}
        model: ${CONTEXA_CHAT_OLLAMA_MODEL:qwen2.5:7b}
        keepAlive: ${CONTEXA_OLLAMA_CHAT_KEEP_ALIVE:30m}
    embedding:
      ollama:
        dedicatedRuntimeEnabled: false
        model: ${CONTEXA_EMBEDDING_OLLAMA_MODEL:mxbai-embed-large}
        dimensions: ${CONTEXA_EMBEDDING_OLLAMA_DIMENSIONS:1024}

For OpenAI or Anthropic, swap in spring-ai-starter-model-openai / spring-ai-starter-model-anthropic and set the API key under contexa.llm.openai.* / contexa.llm.anthropic.*.

Error 3 — rag-vector capability unresolved / SecurityDecisionPostProcessor not created

Root cause — the @EnableAISecurity decision post-processor (SecurityDecisionPostProcessor) depends on UnifiedVectorService, which in turn requires a Spring AI VectorStore bean. Without the pgvector vector-store starter on the classpath, the rag-vector capability stays unresolved and the downstream bean tree never wires up.

Fix — add the pgvector vector-store starter and configure contexa.vectorstore.pgvector.*. Use the pgvector/pgvector:pg16 Docker image so the vector extension is enabled out of the box.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-pgvector'
}

contexa:
  vectorstore:
    pgvector:
      dimensions: 1024
      initialize-schema: true

Infrastructure issues

Container name conflict — The container name "/contexa-postgres" is already in use

Root cause — a container with the same name (contexa-postgres, contexa-ollama, ...) already exists on the host. The Docker daemon does not allow two containers to share a name. Two common cases:

• A previous contexa init run left those containers up — safe to reuse as-is.
• Another project occupies the same name — clean it up, or switch to the isolated simulate mode.

Option 1 — keep the existing containers (recommended, preserves data)

# 1) confirm the containers are running
docker ps --filter "name=contexa-" --format "table {{.Names}}\t{{.Status}}"

# 2) leave them up and just start the app
./gradlew bootRun

Option 2 — remove and recreate (DATA LOSS WARNING)

# Stop + remove (volumes are preserved)
docker rm -f contexa-postgres contexa-ollama
# Distributed mode also needs:
docker rm -f contexa-redis contexa-zookeeper contexa-kafka

# Recreate
contexa init --distributed

Option 3 — switch to the isolated simulation mode (protects production containers)

contexa init --simulate

--simulate namespaces the containers under the ctxa-sim- prefix and shifts ports by +20000, so the simulation stack runs side-by-side with production without colliding.