설치 가이드

빠른 설치 (권장)

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

1단계 — CLI 설치

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

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

2단계 — 프로젝트 초기화

초기화 전에 현재 로컬 개발 환경의 Contexa 구동 적합성을 사전 테스트해 보려면 다음 명령어를 실행하십시오:

contexa init --check

환경 검사 완료 후 아래 명령을 통해 프로젝트의 대화형 자동 설정을 진행합니다:

cd your-spring-project
contexa init

설치 시작 시 Pre-installation 환경 진단이 자동 수행됩니다. 만약 도커 미기동이나 Java 버전 충돌이 감지되면 복구 가이드와 함께 설치 진행이 경고되거나 제한됩니다. 문제가 지속될 시 contexa doctor 진단을 구동하십시오.

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

• 프로젝트 유형 — 신규 프로젝트 (FULL) 또는 레거시 시스템 (SANDBOX)
• AI 보안 모드 — 관찰만 또는 즉시 차단
• AI / LLM 모델 — Ollama (로컬), OpenAI, Anthropic
• 인프라 — Standard (PostgreSQL + Ollama, 단일 서버 인메모리)가 기본. PoC/엔터프라이즈 시연용 분산 모드(Redis + Kafka 포함)는 contexa init --distributed 로 활성화

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

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

3단계 — 어노테이션 추가

@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단계 — 애플리케이션 시작

./gradlew bootRun

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

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

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

Contexa CLI 명령어 레퍼런스

Contexa CLI가 제공하는 주요 명령어를 상세 설명합니다. 터미널에서 contexa <command> [options] 형식으로 실행할 수 있습니다.

사전 요구 사항

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

수동 설치

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

1. 의존성 추가

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. 인프라 시작

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

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

# PoC/시연용 분산 모드 (PostgreSQL + Ollama + Redis + Kafka)
# contexa init --distributed 를 실행하면 docker-compose.yml 에 모두 포함됩니다
docker compose up -d

3. 인프라 서비스

문제 해결

@EnableAISecurity 시동 오류 가이드

수동 설치로 spring-boot-starter-contexa 만 추가하고 @EnableAISecurity 를 선언하면, 시동 시점에 다음 세 가지 오류가 순서대로 노출될 수 있습니다. contexa-cli 가 자동으로 추가하는 의존성은 spring-boot-starter-contexa 한 개뿐이므로, 나머지는 사용자가 본인 빌드에 직접 추가해야 합니다. 각 오류마다 원인과 해결책을 정확히 표시합니다.

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

원인 — Contexa 는 보안 정책·세션·벡터 인덱스를 사용자 운영 DB 와 분리된 전용 PostgreSQL 에 저장합니다. @EnableAISecurity 가 활성화되면 contexa.datasource.url 이 반드시 설정되어 있어야 하며, 미설정 시 ContexaDataSourceIsolation 검증이 즉시 실패합니다.

해결 — 사용자 application.yml 에 contexa 전용 데이터소스 설정을 추가합니다.

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

운영 DB 와 동일 인스턴스에 별도 스키마로 두려면 운영팀과 사전 승인 후 같은 URL 을 사용하실 수 있습니다. 기본은 별도 DB(권장).

오류 2 — No Spring AI ChatModel is configured for CONTEXA

원인 — Contexa 의 LLM 티어 자동 설정(CoreLLMTieredAutoConfiguration) 이 ChatModel 빈을 요구하지만, classpath 에 Spring AI provider starter 가 없습니다. spring-boot-starter-contexa 는 ChatModel starter 를 transitive 의존성으로 끌고 오지 않습니다 — 어떤 provider(Ollama/OpenAI/Anthropic) 를 쓰실지는 사용자 결정이라서입니다.

해결 — 본인이 사용하실 provider starter 한 개 이상을 빌드에 추가하시고, 매칭 설정을 contexa.llm.* 아래에 두십시오. (Contexa 는 Spring AI 의 기본 자동 설정을 타지 않고, 전용 네임스페이스 contexa.llm 을 통해 모델 생성을 제어합니다.)

dependencies {
    implementation 'ai.ctxa:spring-boot-starter-contexa:0.1.0'
    // 아래는 @EnableAISecurity 사용 시 직접 추가 (provider 1개 이상)
    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}

OpenAI 또는 Anthropic 사용 시 spring-ai-starter-model-openai / spring-ai-starter-model-anthropic 으로 교체하시고 contexa.llm.openai.* / contexa.llm.anthropic.* 에 API 키를 설정하십시오.

오류 3 — rag-vector capability unresolved / SecurityDecisionPostProcessor 미생성

원인 — @EnableAISecurity 의 의사결정 후처리기(SecurityDecisionPostProcessor) 가 UnifiedVectorService 를 의존하고, 그 뿌리에는 Spring AI VectorStore 빈이 있습니다. classpath 에 pgvector 벡터스토어 starter 가 없으면 rag-vector capability 가 미해결되어 후속 빈 트리가 생성되지 않습니다.

해결 — pgvector 벡터스토어 starter 를 추가하시고, contexa.vectorstore.pgvector.* 를 설정합니다. PostgreSQL 컨테이너는 pgvector/pgvector:pg16 이미지를 사용하셔야 vector 확장이 자동 활성화됩니다.

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

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

인프라 문제 해결

컨테이너 이름 충돌 — The container name "/contexa-postgres" is already in use

원인 — 같은 이름의 컨테이너(contexa-postgres, contexa-ollama 등) 가 이미 호스트에 존재합니다. Docker 데몬은 같은 이름의 컨테이너 두 개를 동시에 가질 수 없습니다. 보통 다음 두 케이스입니다:

• 이전 contexa init 실행이 만든 컨테이너가 그대로 살아있음 → 그대로 사용해도 무방
• 다른 프로젝트가 같은 이름을 점유 중 → 그쪽을 정리하거나 simulate 격리 모드로 전환

해결 방법 1 — 기존 컨테이너 그대로 사용 (권장, 데이터 보존)

# 1) 기존 컨테이너가 떠있는지 확인
docker ps --filter "name=contexa-" --format "table {{.Names}}\t{{.Status}}"

# 2) 떠있다면 그대로 두고 애플리케이션만 시작
./gradlew bootRun

해결 방법 2 — 기존 컨테이너 제거 후 재생성 (데이터 손실 주의)

# 정지 + 제거 (볼륨은 보존)
docker rm -f contexa-postgres contexa-ollama
# 분산 모드도 같이 정리하려면
docker rm -f contexa-redis contexa-zookeeper contexa-kafka

# 다시 시작
contexa init --distributed

해결 방법 3 — 격리된 시뮬레이션 모드로 전환 (운영 컨테이너 보호)

contexa init --simulate

--simulate 옵션은 컨테이너 이름 prefix 를 ctxa-sim- 로 분리하고 포트도 +20000 으로 띄워, 운영 컨테이너와 충돌 없이 사이드 바이 사이드로 사용할 수 있습니다.