설치 가이드

Contexa AI Native Zero Trust 플랫폼을 Spring 프로젝트에 적용합니다. CLI 자동 설치 또는 수동 설정 중 선택할 수 있습니다.

빠른 설치 (권장)

Contexa CLI를 설치하고 하나의 명령으로 모든 설정을 자동으로 완료합니다.

1단계 — CLI 설치

Shell (Linux / macOS) 
curl -fsSL https://install.ctxa.ai | sh

Windows — 설치 스크립트는 POSIX 셸 스크립트입니다. Windows에서는 Git Bash 또는 WSL에서 실행하세요:

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

또는 contexa-security/contexa-cli에서 CLI 릴리스를 직접 다운로드하여 contexa 바이너리를 PATH에 배치하세요.

2단계 — 프로젝트 초기화

Shell 
cd your-spring-project
contexa init

CLI가 대화형으로 설정을 안내합니다:

  • 프로젝트 유형 — 신규 프로젝트 (FULL) 또는 레거시 시스템 (SANDBOX)
  • AI 보안 모드 — 관찰만 또는 즉시 차단
  • AI / LLM 모델 — Ollama (로컬), OpenAI, Anthropic
  • 인프라 — Standard (PostgreSQL + Ollama) 또는 Distributed (+ Redis + Kafka)

CLI가 자동으로 수행하는 작업:

  • 빌드 파일에 spring-boot-starter-contexa 의존성 추가
  • application.yml에 올바른 설정 구성
  • 인프라용 docker-compose.yml 생성
  • Docker 컨테이너 시작 및 AI 모델 다운로드

3단계 — 어노테이션 추가

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

// AI Zero Trust로 보호할 엔드포인트에 추가
@Protectable
@GetMapping("/api/customers")
public List<Customer> getCustomers() { ... }

4단계 — 애플리케이션 시작

Shell 
./gradlew bootRun

설정 완료. AI 기반 Zero Trust 보안이 활성화되었습니다. @Protectable 엔드포인트에 대한 모든 요청이 AI에 의해 실시간 분석됩니다.

레거시 시스템 연동 (SANDBOX 모드)

프로젝트에 이미 자체 인증 시스템이 있다면 SANDBOX 모드를 사용하세요. 기존 로그인을 수정하지 않고 AI 보안을 추가합니다.

Java 
@EnableAISecurity(
    mode = SecurityMode.SANDBOX,
    authObjectLocation = AuthObjectLocation.SESSION,
    authObjectAttribute = "loginUser"  // 레거시 세션 속성명
)
@SpringBootApplication
public class LegacyApplication { }

사이드 이펙트 제로 — SANDBOX 모드는 기존 보안에 간섭하지 않습니다. 로그인 페이지, 세션 관리, 접근 제어가 그대로 유지됩니다. Contexa는 @Protectable 엔드포인트에서만 동작합니다.

사전 요구 사항

CLI 및 수동 설치 모두에 필요합니다:

요구 사항 버전 용도
Java 21+ 런타임 (Gradle 툴체인으로 구성)
Spring Boot 3.x 애플리케이션 프레임워크
Docker 최신 버전 인프라 서비스 (PostgreSQL, Ollama)

Distributed 모드 전용 — Distributed 모드를 사용하려면 Redis (세션 저장소, 분산 락)와 Kafka (이벤트 스트리밍)가 추가로 필요합니다.

수동 설치

CLI를 사용하지 않으려면 다음 단계를 수동으로 진행합니다.

1. 의존성 추가

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>

2. 인프라 시작

Shell 
# Standard 모드 (PostgreSQL + Ollama)
docker compose up -d

# Distributed 모드 (+ Redis + Kafka)
docker compose --profile distributed up -d

# AI 모델 다운로드
docker exec contexa-ollama ollama pull qwen3.5:9b
docker exec contexa-ollama ollama pull mxbai-embed-large

3. 인프라 서비스

서비스 이미지 포트 모드
PostgreSQL pgvector/pgvector:pg16 5432 Standard
Ollama ollama/ollama:latest 11434 Standard
Redis redis:7.2-alpine 6379 Distributed
Kafka cp-kafka:7.4.0 9092 Distributed

문제 해결

문제 해결 방법
PostgreSQL 연결 거부 Docker 실행 확인: docker ps. 포트 5432 사용 여부 확인.
Ollama 연결 거부 컨테이너 로그 확인: docker logs contexa-ollama. 포트 11434 확인.
AI 모델 미발견 모델 다운로드: docker exec contexa-ollama ollama pull qwen3.5:9b
포트 충돌 기본 포트: PostgreSQL 5432, Ollama 11434, Redis 6379, Kafka 9092
contexa init — 화살표 키 미작동 Windows: Git Bash에서 winpty contexa init 사용, 또는 Windows Terminal에서 실행

도움이 필요하신가요? — 설정 레퍼런스를 확인하거나 GitHub Discussions를 방문하세요.