설치 가이드

CLI 설치와 프로젝트 초기화

서명 검증된 CLI를 설치하고 Spring Boot 프로젝트에서 Quick 또는 Custom을 선택합니다. 모든 경로는 파일·의존성·인프라·Docker 변경 계획을 실제 적용 전에 표시합니다.

1단계 — CLI 설치

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

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

2단계 — 진단 및 초기화

cd your-spring-project
contexa init --check   # 선택 사항, 읽기 전용
contexa init

3단계 — 생성 상태 확인

• Merge: build를 갱신하고 application-contexa.yml을 생성하며, 자동 어노테이션을 선택한 경우에만 메인 소스를 변경합니다. 호스트 application.yml은 보존합니다.
• Standalone 통합: 별도 디렉터리에 Contexa YAML과 Gradle/Maven fragment를 생성합니다. 호스트 build·YAML·소스는 변경하지 않으며 사용자가 생성 fragment를 연결합니다.
• Standalone 인프라: PostgreSQL과, Ollama가 선택된 경우에만 Ollama를 생성합니다.
• Distributed 인프라: PostgreSQL·Redis·ZooKeeper·Kafka와, 선택된 경우에만 Ollama를 생성합니다.
• Skip 인프라: Compose 파일과 Docker 변경이 없습니다.

4단계 — 실행·상태 확인·원복

./gradlew bootRun
contexa status
contexa reset

reset은 manifest에 기록된 CLI 소유 상태만 복원합니다. 사용자가 수정한 파일을 임의로 덮어쓰거나 무관한 인프라를 삭제하지 않습니다.

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

프로젝트가 이미 인증·인가를 소유한다면 SANDBOX/HOST_OWNED를 사용하세요. 호스트가 인증한 principal을 브리지 입력으로 전달한 뒤 Contexa Zero Trust runtime은 별도로 동작합니다.

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

Contexa CLI 명령어 레퍼런스

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

사전 요구 사항

모든 설치 경로에는 Java와 Spring Boot 프로젝트가 필요합니다. Quick에서 생성한 Standalone 인프라를 CLI가 시작하게 하려면 Docker가 필요합니다. --no-docker 또는 Custom의 Skip을 선택하면 필요한 외부 인프라는 사용자가 준비합니다.

수동 설치

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

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. 선택 기능만 구성

Starter의 공통 기본값은 *Properties에 있습니다. 수동 dependency-only 통합에서는 application.yml이나 Docker Compose 파일을 추가할 필요가 없습니다.

문제 해결

@EnableAISecurity 시동 오류 가이드

수동 dependency-only 통합에 @EnableAISecurity를 직접 추가했거나, Custom에서 외부 인프라를 선택한 뒤 필수 provider·데이터베이스 설정을 누락하거나, 생성된 설정을 제거하면 다음 오류가 발생할 수 있습니다. Quick은 선택한 provider 의존성, 소스 어노테이션, Standalone 데이터베이스 구성을 함께 생성합니다.

오류 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 으로 띄워, 운영 컨테이너와 충돌 없이 사이드 바이 사이드로 사용할 수 있습니다.