빠른 시작

시작하기

검증된 CLI로 Spring Boot 프로젝트에 Contexa를 구성하세요. 바로 실행 가능한 로컬 구성은 Quick, 통합·보안 소유권·provider·인프라·Docker 기동을 정확히 제어하려면 Custom을 선택합니다.

사전 요구 사항

Java와 Spring Boot는 항상 필요합니다. Compose만 생성할 때 Docker는 선택 사항이며, Quick은 선택한 PostgreSQL과 Ollama 서비스를 자동으로 준비할 수 있습니다.

요구 사항 버전 비고
Java 17+ LTS 릴리스
Spring Boot 3.x 현재 검증 기준 3.5.4, 4.x 미지원
15+ Quick이 전용 서비스를 생성하며, 수동 dependency-only 통합에는 불필요
Ollama 선택 Latest Ollama를 AI provider로 선택할 때만 필요

선택: 데이터베이스 설정

Quick은 전용 PostgreSQL 서비스를 생성합니다. Custom에서 외부 인프라를 사용하거나 수동 dependency 경로를 따를 때만 데이터베이스를 직접 생성하십시오.

SQL 
CREATE DATABASE contexa;
\c contexa
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

선택: Ollama 모델

AI provider로 Ollama를 선택한 경우에만 선택한 채팅·임베딩 모델을 다운로드하세요.

Shell 
ollama pull qwen2.5:7b
ollama pull mxbai-embed-large

설치기는 검증된 contexa 실행 파일만 설치합니다. Spring 프로젝트는 contexa init이 변경 계획을 보여 주고 사용자가 확인한 뒤에만 변경됩니다.

1. CLI 설치 및 확인

Linux / macOS
curl -fsSL https://install.ctxa.ai/install.sh | sh
Windows PowerShell 5.1+
irm https://install.ctxa.ai/install.ps1 | iex
확인
contexa --version

2. Quick 또는 Custom 선택

Shell
cd your-spring-project
contexa init
선택적용 결과적합한 경우
QuickMerge, FULL, SHADOW, provider 하나, 선택적 자동 @EnableAISecurity, Standalone 인프라, 사용 가능한 경우 Docker 기동최소 질문으로 바로 실행 가능한 로컬 구성이 필요한 경우
CustomMerge/Standalone, FULL/SANDBOX, SHADOW/ENFORCE, provider, Standalone/Distributed/Skip 인프라, 경로와 Docker 기동 여부를 직접 선택호스트 소유 IAM, 외부 인프라 또는 정확한 배포 요구 사항이 있는 경우

Quick은 dependency-only가 아닙니다. 첫 질문에서 Enter를 누르면 Quick입니다. provider와 자동 어노테이션 여부를 선택한 뒤 Starter와 선택한 Spring AI 의존성을 추가하고, application-contexa.yml을 생성하며, 선택에 따라 메인 클래스에 어노테이션을 추가합니다. PostgreSQL과, Ollama를 선택한 경우에만 Ollama Compose 서비스를 생성하고 Docker가 사용 가능하면 기동합니다. 호스트 application.yml은 변경하지 않습니다.

--yes 기본값 — Ollama, 자동 어노테이션, Standalone PostgreSQL/Ollama 인프라와 Docker 기동입니다. 컨테이너를 시작하지 않고 Compose만 생성하려면 --no-docker를 추가하십시오.

3. 명시적 실행 예제

Shell
contexa init --yes --provider openai --no-docker
contexa init --standalone --security-mode sandbox --provider openai --no-docker
contexa init --yes --distributed --provider openai --no-docker

Merge 통합은 선택한 의존성과 선택적 소스 어노테이션을 적용하되 Contexa 설정은 전용 overlay에 기록합니다. Standalone 통합은 호스트 build·YAML·소스를 변경하지 않고 수동 연결용 설정과 build fragment를 생성합니다. Standalone 통합과 Standalone 인프라는 서로 다른 선택입니다.

4. 상태 확인·simulation·원복

Shell
contexa status
contexa reset
contexa init --simulate --yes --no-docker
contexa reset --simulate --yes

simulation은 Starter가 이미 있는 프로젝트에서 실행합니다. 각 reset은 해당 ownership manifest에 기록된 자원만 복원하며 일반 설치와 simulation 상태는 서로 독립적입니다.

수동 dependency-only는 별도 경로입니다. 사용자가 ai.ctxa:spring-boot-starter-contexa:0.1.0만 직접 추가하고 @EnableAISecurity를 선언하지 않으면 AI 보안은 활성화되지 않으며 호스트의 인증·인가와 SecurityContext 소유권이 유지됩니다. 이것은 CLI Quick의 결과가 아닙니다.

1

수동 설치: Starter 의존성 추가

CLI를 사용하지 않는 경우 Maven Central의 Starter 한 개만 추가하세요. 안정 버전에는 mavenCentral() 외의 milestone·snapshot 저장소가 필요하지 않습니다.

Gradle (Kotlin DSL) 
dependencies {
    implementation("ai.ctxa:spring-boot-starter-contexa:0.1.0")
}
Gradle (Groovy) 
dependencies {
    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>

선택 의존성 — 수동 구성에서는 사용자가 선택한 provider starter만 추가하고 해당 경로에 필요한 저장소 드라이버를 구성하십시오. 사용하지 않는 provider를 추가하지 마십시오.

2

선택: AI 보안 활성화

수동으로 AI Zero Trust를 활성화할 때 @EnableAISecurity를 추가합니다. 호스트가 인증을 소유하는 경우 SANDBOX를 사용하며, Contexa는 호스트 IAM을 대체하지 않고 기존 principal을 브리지 입력으로 사용합니다.

Java 
@SpringBootApplication
@EnableAISecurity(mode = SecurityMode.SANDBOX)
public class MyApplication {

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

소유권 계약 — 기본 SANDBOX는 HOST_OWNED, 명시적 FULL은 CONTEXA_OWNED로 연결됩니다. 레거시 시스템에서는 호스트 IAM을 수정하거나 대체하지 말고 SANDBOX를 사용하십시오.

3

선택 기능만 설정

Contexa의 공통 기본값은 Starter의 *Properties에 있습니다. 사용하지 않는 기능의 값을 application.yml에 복사하지 말고, provider·데이터베이스·분산 인프라를 명시 선택한 경우에만 필요한 값을 설정하세요.

YAML 
# 수동 dependency-only 설치
# 추가 application.yml 설정 없음

# AI 보안·provider·데이터베이스·분산 인프라를 선택한 경우에만
# 해당 기능에 필요한 설정을 추가합니다.

LLM 설정 — AI 보안을 켜고 provider를 선택한 경우에만 해당 provider의 API key 또는 로컬 endpoint를 설정합니다. 수동 dependency-only 애플리케이션에는 LLM 설정이 필요하지 않습니다.

Ollama 선택 시 — 세부 옵션은 AI 설정 참조에서 확인하세요. 문서의 모든 예제를 복사하지 말고 실제로 사용하는 모델과 runtime만 설정합니다.

고급 provider 선택 — 다중 provider 우선순위와 fallback은 필수 설치 절차가 아닙니다. 단일 provider 기동을 먼저 확인한 뒤 필요할 때만 구성하세요.

4

실행 및 확인

호스트 애플리케이션을 평소 방식으로 시작하세요. dependency-only 상태와 명시적 AI 보안 활성 상태를 구분해 확인합니다.

Shell 
# Gradle
./gradlew bootRun

# Maven
mvn spring-boot:run

확인: 자동 설정 리포트

--debug 플래그를 사용하여 어떤 Contexa 자동 설정이 적용되었는지 확인하세요:

Shell 
./gradlew bootRun --args='--debug'

@EnableAISecurity를 선언한 경우에만 선택한 Contexa 자동 설정이 활성화됐는지 확인하세요. dependency-only 상태에서는 Contexa 보안 필터와 provider가 없어야 정상입니다.

확인: Actuator Health 엔드포인트

의존성에 spring-boot-starter-actuator가 없다면 추가한 후, Health 엔드포인트를 확인하세요:

Shell 
curl http://localhost:8080/actuator/health

조건부 데이터베이스 — 수동 dependency-only 상태에는 Contexa 데이터베이스가 필요하지 않습니다. 영속화·IAM·벡터 기능을 활성화한 경우에만 전용 PostgreSQL 연결과 권한을 확인하세요. 테이블은 CLI가 아니라 해당 runtime의 서버 기동 과정에서 생성·검증합니다.

메서드 수준 보안

첫 번째 메서드 보호하기

AI 보안을 명시적으로 활성화한 뒤 Zero Trust 분석 대상 메서드에만 @Protectable을 추가하세요. sync = true는 메서드 반환 전에 최종 결정을 적용하고, 기본값 sync = false는 호스트 요청을 즉시 진행하면서 비동기 분석 증거를 기록합니다.

Java 
@Service
public class OrderService {

    @Protectable
    public Order getOrder(Long orderId) {
        return orderRepository.findById(orderId)
                .orElseThrow(() -> new OrderNotFoundException(orderId));
    }
}

DB 정책 계약 — 접근 판정은 DB의 활성·승인된 정책을 리소스에 결합해 실행합니다. 해당 리소스에 적용할 DB 정책이 없으면 Contexa 정책 계층은 기본적으로 허용하며, 호스트 애플리케이션의 기존 인증·인가는 그와 별도로 계속 적용됩니다.

@Protectable 속성

속성 타입 기본값 설명
ownerField String "" 소유권 기반 인가 검사를 위해 리소스 소유자를 식별하는 반환 타입의 필드명.
sync boolean false true로 설정하면 메서드가 반환되기 전에 Zero Trust 평가가 동기적으로 완료됩니다. false(기본값)인 경우 평가가 비동기적으로 실행되고 메서드는 즉시 진행됩니다.
AI 결정

다음 단계 — Zero Trust Actions

Contexa가 평가하는 모든 요청은 다음 ZeroTrustAction 결정 중 하나를 생성합니다. AI 엔진은 행동 분석, 위협 평가, 신뢰 점수를 기반으로 적절한 조치를 결정합니다.

액션 HTTP 상태 TTL 동작
ALLOW 200 15s 요청이 정상적으로 처리됩니다
BLOCK 403 영구 요청이 거부됩니다; 사용자에게 ROLE_BLOCKED가 부여됩니다
CHALLENGE 401 1800s 추가 인증이 필요합니다 (MFA); 사용자에게 ROLE_MFA_REQUIRED가 부여됩니다
ESCALATE 423 300s 수동 검토를 위해 요청이 보류됩니다; 사용자에게 ROLE_REVIEW_REQUIRED가 부여됩니다
PENDING_ANALYSIS 503 0s AI 분석이 진행 중입니다; 사용자에게 ROLE_PENDING_ANALYSIS가 부여되며 평가가 완료될 때까지 요청이 지연됩니다

AI 기반 결정 — 기존의 규칙 기반 시스템과 달리, Contexa의 LLM 엔진은 실시간 행동 분석을 기반으로 각 요청에 대한 적절한 조치를 결정합니다. 정적 규칙을 설정할 필요 없이 AI가 애플리케이션의 트래픽 패턴을 학습하고 적응합니다.

다음 단계

전체 문서를 탐색하여 고급 기능, 설정 옵션, 아키텍처 세부 사항을 알아보세요.

Spring Boot 통합

Identity DSL을 설정하고, 인증 흐름을 커스터마이즈하고, CustomDynamicAuthorizationManager와 통합하세요.

문서 보기 →

Core — AI 엔진

AI 파이프라인 아키텍처, 모델 설정, SSE 스트리밍.

문서 보기 →

Zero Trust 아키텍처

이중 흐름 아키텍처, AISecurityContextRepository, 지속적 신뢰 평가.

문서 보기 →

@Protectable 레퍼런스

XACML 정책 엔진, 동적 인가, 메서드 수준 보호.

문서 보기 →

설정 레퍼런스

contexa.*, spring.ai.*, 인프라 모드에 대한 전체 속성 레퍼런스.

문서 보기 →

Shadow Mode 가이드

2단계 마이그레이션 경로: 관찰을 위한 Shadow 모드, 전체 AI 적용을 위한 Enforce 모드.

문서 보기 →