# WildFly 기반 배포 이해

Keycloak는 본래 WildFly 애플리케이션 서버 위에서 동작하도록 설계된 프로젝트로 시작되었다. 이는 Keycloak가 WildFly 서버에 배포되는 형태로 제공되었다는 뜻이며, WildFly의 모듈, 서브시스템, 설정 파일 등을 활용한다. 이 장에서는 WildFly 기반 Keycloak 서버의 동작 원리와 구조를 엄밀하게 살펴본다.

### Keycloak와 WildFly의 관계

Keycloak는 Java EE 애플리케이션 서버인 WildFly를 확장하는 형태로 동작한다. 이때 Keycloak는 자체적으로 구성된 모듈을 WildFly에 추가하고, WildFly의 서비스와 통합하여 인증·인가 기능을 제공한다. 결과적으로 WildFly 기반 배포판은 다음과 같은 특징을 가진다.

* **WildFly 서버 동봉** Keycloak WildFly 배포판은 사실상 WildFly 서버를 포함하고 있다. 즉, 일반 WildFly 바이너리에 Keycloak 관련 모듈과 설정이 추가된 형태이며, 별도 서버가 아니라 하나의 통합 서버로 동작한다.
* **서브시스템(Subsystem) 확장** Keycloak는 WildFly가 제공하는 Undertow 서브시스템, JPA 서브시스템 등과 유기적으로 연동된다. Keycloak 자체 서브시스템이 존재하며, 이를 통해 사용자 인증·인가 로직을 수행한다.
* **관리 CLI(Management CLI) 및 설정 파일 재사용** WildFly가 제공하는 `standalone.xml` 혹은 `domain.xml` 파일을 기반으로 Keycloak 설정이 정의된다. WildFly 관리자 CLI를 통해 설정을 변경할 수도 있으며, Keycloak 운영에 필요한 JDBC 드라이버, datasource, 로그 설정 등을 WildFly 표준 방식대로 관리할 수 있다.

### WildFly 기반 Keycloak 서버 구조

WildFly 배포판 내부에서 Keycloak는 핵심 기능을 담당하는 특정 모듈들과 확장 포인트를 통해 WildFly에 결합된다. 일반적으로 다음 디렉터리 구성을 확인할 수 있다.

* **modules/** WildFly 모듈을 저장하는 디렉터리다. Keycloak 관련 라이브러리가 `org/keycloak` 등 특정 경로로 등록되어 있으며, WildFly의 모듈 로딩 메커니즘을 통해 Keycloak 기능을 활성화한다.
* **standalone/** WildFly의 단일 서버(standalone) 운영 모드 설정 파일이 위치한다. `standalone.xml` 혹은 `standalone-ha.xml`에 Keycloak 서브시스템, 데이터소스, Undertow 설정 등이 포함되어 있다.
* **domain/** WildFly 도메인(domain) 모드 운영 시 사용하는 설정 파일(`domain.xml`, `host.xml`)이 위치한다. 여러 노드가 하나의 도메인 컨트롤러(domain controller)에 의해 관리되는 환경에서도 Keycloak를 배포할 수 있다.
* **deployments/** WAR나 EAR 형태의 Java EE 애플리케이션 배포 디렉터리다. Keycloak는 보통 WildFly 내부 구성으로 이미 포함되어 있으나, 추가적으로 어댑터나 기타 애플리케이션을 배포해야 하는 경우 이 디렉터리를 활용한다.

### 동작 방식

WildFly 기반 배포판을 실행하면 내부적으로 WildFly가 기동되면서 다음 과정을 수행한다.

1. **WildFly 부팅** WildFly의 메인 실행 스크립트(`standalone.sh` 또는 `domain.sh`)가 호출되어 서버가 부팅된다.
2. **모듈 및 서브시스템 로딩** WildFly는 `modules/` 디렉터리의 Keycloak 모듈을 로딩하며, 설정 파일(`standalone.xml` 또는 `domain.xml`) 내 정의된 Keycloak 서브시스템을 초기화한다.
3. **Keycloak 서비스 초기화** Keycloak 서브시스템이 동작하기 위해 필요한 DataSource, 캐시 설정(Infinispan), 메트릭, HTTP 리스너(Undertow), 각종 확장 포인트가 준비된다. Keycloak는 이를 토대로 사용자 인증·인가, 토큰 발급, Admin 콘솔 제공 등의 기능을 수행한다.
4. **관리 인터페이스 활성화** Keycloak Admin 콘솔은 기본적으로 WildFly의 Undertow 서브시스템을 통해 제공된다. `http://<hostname>:8080/auth/admin/`와 같은 경로에서 Keycloak 관리자 UI에 접근할 수 있게 된다.

### 배포 모드: Standalone vs Domain

WildFly는 두 가지 모드(standalone, domain)로 서버를 운영할 수 있다. Keycloak 또한 이를 동일하게 지원한다.

* **Standalone 모드** 단일 WildFly 인스턴스를 Keycloak 서버로 사용한다. 개발 환경이나 소규모 운영 환경에서 주로 사용하며, 설정 파일(`standalone.xml`)만 수정하면 된다.
* **Domain 모드** 여러 WildFly 호스트를 도메인 컨트롤러 하나가 통합 관리하는 방식이다. 대규모 환경에서 Keycloak 클러스터를 구성할 때 유용하지만, 설정이 복잡해진다. 이때 `domain.xml`과 `host.xml`을 적절히 편집해야 한다.

### 설정 관리

WildFly 기반 Keycloak 설정은 일반 WildFly 설정 방식과 유사하다. 예를 들어 데이터베이스를 변경하려면 WildFly 표준 datasource 설정을 편집하거나 CLI 명령어를 통해 datasource를 추가한다. Keycloak는 이 datasource를 사용해 Realm 정보, 사용자 계정, 세션 정보를 저장한다.

* **standalone.xml 예시**

  ```
  <subsystem xmlns="urn:jboss:domain:keycloak:1.0">
      <!-- Keycloak 서브시스템 관련 설정 -->
  </subsystem>

  <subsystem xmlns="urn:jboss:domain:datasources:5.0">
      <datasources>
          <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakPool">
              <connection-url>jdbc:postgresql://localhost:5432/keycloak</connection-url>
              <driver>postgresql</driver>
              <security>
                  <user-name>keycloakuser</user-name>
                  <password>password</password>
              </security>
          </datasource>
      </datasources>
  </subsystem>
  ```
* **CLI 명령어 예시**

  ```
  # JDBC 드라이버 추가
  module add --name=org.postgresql --resources=/path/to/postgresql-driver.jar --dependencies=javax.api,javax.transaction.api

  # 데이터소스 등록
  /subsystem=datasources/data-source=KeycloakDS:add(jndi-name=java:jboss/datasources/KeycloakDS,driver-name=postgresql,connection-url=jdbc:postgresql://localhost:5432/keycloak,user-name=keycloakuser,password=password)
  ```

### 운영 시 고려 사항

* **업그레이드** WildFly 기반 Keycloak 배포판은 내부 WildFly 버전에 종속적이다. Keycloak를 업그레이드할 때는 WildFly 버전도 함께 상승하는 경우가 많으므로, 호환성 테스트가 필요하다.
* **클러스터링** WildFly의 Infinispan 서브시스템을 활용해 세션 및 캐시를 클러스터링할 수 있다. 다수 노드의 Keycloak 서버가 세션 정보를 공유하려면 standalone-ha.xml(혹은 domain 모드의 ha 프로파일)을 사용하거나 Infinispan 설정을 정확히 잡아야 한다.
* **로그 관리** WildFly 표준 로깅 시스템을 따르므로, JBoss Log Manager 또는 log4j 설정을 통해 Keycloak 로그를 관리한다. 운영 환경에서는 로그 파일의 용량, 회전 정책, 중앙화 등을 WildFly 수준에서 설계해야 한다.
* **Quarkus 배포판과의 차이** Keycloak 최신 버전은 Quarkus 기반 배포판도 함께 제공한다. Quarkus 배포판은 경량화와 독립 실행 방식을 추구하지만, WildFly 기반 배포판은 전통적인 Java EE 애플리케이션 서버 모델에 익숙한 환경에서 운용하기 쉽다.

WildFly 기반 배포는 오랜 기간 사용되어 온 안정적인 방식이며, 기존 WildFly 환경을 유지하거나 JBoss EAP 호환성을 원하는 경우 선호된다. 반면에 최신 기능이나 경량 런타임을 원한다면 Quarkus 기반 Keycloak를 검토해볼 수 있다.

### 정리

WildFly 기반 Keycloak 서버는 전통적인 Java EE 애플리케이션 서버 모델 위에서 Keycloak가 동작하도록 구성된 형태다. 내부적으로 WildFly 서브시스템, 모듈, 설정 파일에 Keycloak가 결합되어 있으며, 이를 통해 인증·인가, 세션 관리, Admin 콘솔 서비스 등이 제공된다. 도메인 모드와 스탠드얼론 모드 모두 지원하고, 표준 WildFly 관리 방식을 그대로 사용할 수 있다는 점이 특징이다. 운영 환경 요구사항과 조직의 기술 스택에 따라 WildFly 기반 혹은 Quarkus 기반 배포판을 선택하면 된다.