설치 가이드

빠른 설치 (권장)

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 보안을 추가합니다. SANDBOX 모드는 기본적으로 HOST_OWNED로 동작하므로, 인증과 인가는 애플리케이션의 Spring Security 설정이 계속 담당합니다.

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

@Configuration
public class HostSecurityConfig {

    @Bean
    public SecurityFilterChain hostSecurityFilterChain(HttpSecurity http) throws Exception {
        // 페이지 보호는 기존 레거시 필터가 계속 담당합니다
        http.authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
        return http.build();
    }
}

이 체인에도 Spring Security의 기본 설정(CSRF 보호, 보안 응답 헤더 등)은 적용되므로, 기존 동작과 다른 부분은 애플리케이션 요구에 맞게 조정하세요.

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