설치 개요
Contexa CLI 설치와 Spring 프로젝트 초기화는 분리되어 있습니다. contexa init은 즉시 사용할 수 있는 Quick 구성과 항목별로 선택하는 Custom 구성을 제공하며, 수동 dependency-only 통합은 별도 경로입니다.
사전 요구 사항
Contexa를 설치하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요:
| 요구 사항 | 최소 버전 | 비고 |
|---|---|---|
| Java | 17+ | LTS 릴리스 (17) |
| Spring Boot | 3.5.4 | 스타터 BOM으로 관리 (Jakarta EE 네임스페이스) |
| Spring Security | 6.2+ | Spring Boot Starter를 통해 전이적으로 포함 |
| Docker 조건부 | 지원 버전 | CLI가 Compose 서비스를 시작할 때 필요. --no-docker이면 불필요 |
| PostgreSQL CLI 관리 또는 외부 | 15+ | Quick이 전용 서비스를 생성하며, Custom의 외부 인프라 경로에서는 사용자가 준비 |
| Redis Distributed 전용 | 7.0+ | Distributed 모드 전용 — 공유 캐싱 및 이벤트 스트리밍에 필요 |
LLM 요구 사항 — Quick은 provider 하나를 선택하며 기본값은 로컬 Ollama입니다. Custom은 하나 이상의 provider를 선택합니다. 수동 dependency-only 통합에는 LLM 설정이 필요하지 않습니다.
수동 dependency-only — Starter만 직접 추가하고 @EnableAISecurity를 사용하지 않으면 Contexa가 호스트 보안에 관여하지 않습니다. 이는 Quick 기본값이 아닙니다. CLI는 제품 테이블을 직접 생성하지 않으며, 활성화된 OSS 또는 Enterprise runtime이 서버 기동 시 자신의 스키마를 생성·검증합니다.
모듈 아키텍처
Contexa는 각각 고유한 보안 도메인을 담당하는 모듈식 레이어로 구성됩니다. Spring Boot Starter는 모든 모듈을 단일 의존성으로 통합합니다.
| 모듈 | 아티팩트 | 역할 |
|---|---|---|
| Starter | spring-boot-starter-contexa |
통합 의존성; 모든 모듈을 제공하되 실제 보안 구성은 활성화 조건에 따라 로드 |
| Common | contexa-common |
공유 어노테이션(@EnableAISecurity, @Protectable), 열거형, 엔티티 모델, 캐시 추상화 |
| Core | contexa-core |
AI 파이프라인, LLM 오케스트레이션, HCAD 엔진, Zero Trust 평가, RAG 및 벡터 스토어 통합 |
| Identity | contexa-identity |
Identity DSL, 인증 흐름(폼, REST, OTT, 패스키), 적응형 MFA, 세션 관리 |
| IAM | contexa-iam |
XACML 정책 엔진, @Protectable 메서드 인터셉션, 동적 인가, 관리자 대시보드 |
| Auto-Configure | contexa-autoconfigure |
모든 모듈의 Spring Boot 자동 구성; 클래스패스 및 속성에 기반한 조건부 빈 등록 |
인프라 모드
Quick은 Standalone 인프라를 선택하여 PostgreSQL과, Ollama 선택 시 Ollama 서비스를 Compose로 생성합니다. Custom에서는 Standalone·Distributed·Skip 중 하나를 선택합니다.
Standalone 인프라
PostgreSQL과 선택한 Ollama 서비스를 프로젝트 전용 Compose로 생성합니다. Docker를 사용할 수 있으면 Quick은 기본적으로 시작하고, --no-docker는 파일만 생성합니다.
Distributed 모드
Custom 또는 --distributed로 명시적으로 선택합니다. PostgreSQL, Redis, ZooKeeper, Kafka와 선택한 Ollama 서비스를 구성합니다.
설치 경로
필요에 가장 적합한 경로를 선택하세요:
의존성 좌표
안정 버전은 Maven Central의 ai.ctxa 그룹으로 게시됩니다. 권장 진입점은 Starter 한 개이며, mavenCentral() 외의 milestone·snapshot 저장소는 필요하지 않습니다.
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>