# 학습 환경 구성

Keycloak을 학습하기 위해서는 로컬 환경에 Keycloak 서버를 설치하고 실행하는 방법을 먼저 알아두는 것이 중요하다. 이 장에서는 Keycloak 서버를 손쉽게 설치하고 실행하기 위한 사전 준비 사항과 구체적인 설치 과정을 다룬다.

### 사전 준비

* **운영 체제**: Windows, macOS, Linux 등 주요 운영 체제에서 모두 동작한다.
* **Java 버전**: Keycloak은 Java 17 이상 또는 LTS 버전(11, 17)을 권장한다. 다만 최신 릴리스 노트를 참고해 호환성을 확인해야 한다.
* **메모리 및 디스크 용량**: 운영 체제와 Java를 안정적으로 구동할 수 있는 충분한 자원을 확보한다(테스트용으로 최소 2GB 이상의 메모리 권장).

Keycloak 최신 버전부터는 Quarkus 기반으로 동작하므로, 과거 WildFly 기반 버전 대비 실행 방식과 설정이 다소 달라졌을 수 있다. 학습 과정에서 사용하는 Keycloak 버전에 맞는 공식 문서를 반드시 확인해 둘 필요가 있다.

### Keycloak 설치 방법 개요

Keycloak 설치는 크게 다음 두 가지 방식으로 진행할 수 있다.

1. **공식 배포판(zip/tar.gz) 다운로드 후 직접 실행** Java가 사전에 설치되어 있어야 하며, 아카이브 파일을 다운로드 받아 압축을 해제한 뒤 실행 스크립트를 통해 Keycloak 서버를 구동한다.
2. **Docker 이미지를 활용한 설치** Docker 환경에서 Keycloak 공식 이미지를 받아 컨테이너로 구동한다. 시스템에 Docker만 설치되어 있으면 의존성 설정이 단순하고 빠르게 실행할 수 있어, 가장 간편한 방법으로 꼽힌다.

아래에는 학습 목적으로 가장 쉽게 시도할 수 있는 Docker 기반 설치 방법을 중심으로 소개한다.

### Docker 환경에서의 Keycloak 설치

#### 1. Docker 설치 확인

* 로컬 환경에 Docker가 설치되어 있지 않다면 [Docker 공식 사이트](https://www.docker.com/)에서 운영 체제에 맞는 버전을 다운로드하고 설치한다.
* 설치 후 `docker version` 명령을 통해 정상 동작 여부를 확인한다.

#### 2. Keycloak Docker 이미지 받기

* Keycloak 공식 Docker 이미지는 [Quay.io](https://quay.io/)나 [Docker Hub](https://hub.docker.com/)에서 제공된다.
* 일반적으로 다음 명령어를 통해 이미지를 받을 수 있다.

  ```bash
  docker pull quay.io/keycloak/keycloak:latest
  ```

  혹은

  ```bash
  docker pull docker.io/jboss/keycloak:latest
  ```

  버전에 따라 이미지 레포지토리나 태그가 달라질 수 있으니, 사전에 공식 문서나 Docker Hub/Quay.io에서 확인한다.

#### 3. Keycloak 서버 컨테이너 실행

* Keycloak 실행 시에는 최소한 관리자 계정 생성을 위한 환경 변수가 필요하다.
* 예시 실행 명령:

  ```bash
  docker run -d \
    --name my-keycloak \
    -p 8080:8080 \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin123 \
    quay.io/keycloak/keycloak:latest start-dev
  ```

  * `-d`: 백그라운드에서 컨테이너를 실행한다.
  * `--name my-keycloak`: 컨테이너 이름을 `my-keycloak`로 지정한다.
  * `-p 8080:8080`: 호스트의 8080 포트와 컨테이너의 8080 포트를 매핑한다.
  * `-e KEYCLOAK_ADMIN=admin, KEYCLOAK_ADMIN_PASSWORD=admin123`: Keycloak 관리자 계정 정보. 실제 환경에서는 보안을 위해 안전한 비밀번호를 사용해야 한다.
  * `start-dev`: 개발 모드로 Keycloak을 구동한다. 운영 환경에서는 별도의 매개변수 설정이 필요하다.

#### 4. 실행 확인

* 컨테이너가 정상적으로 구동되었다면 웹 브라우저에서 `http://localhost:8080`으로 접속해 Keycloak 초기 화면을 확인한다.
* Keycloak 관리자 콘솔에 접속하기 위해서는 `http://localhost:8080/admin`(버전에 따라 경로가 조금 다를 수 있음)에 접속한 후, 앞서 설정한 관리자 계정(`admin / admin123`)으로 로그인한다.

#### 5. 종료 및 삭제

* 실행 중인 컨테이너 확인:

  ```bash
  docker ps
  ```
* 특정 컨테이너 종료:

  ```bash
  docker stop my-keycloak
  ```
* 특정 컨테이너 삭제:

  ```bash
  docker rm my-keycloak
  ```
* 이미지 삭제:

  ```bash
  docker rmi quay.io/keycloak/keycloak:latest
  ```

  학습 용도로 여러 번 재설치할 경우에는 이미지 삭제 없이 그대로 다시 실행하거나, 필요한 버전만 유지할 수도 있다.

### 공식 배포판(zip/tar.gz)으로 설치하기

Docker 환경 사용이 어려운 경우, 혹은 Keycloak의 내부 작동 방식에 대해 좀 더 심도 있게 학습하고자 한다면 공식 배포판을 다운로드해 직접 구동할 수 있다.

1. **배포판 다운로드** [Keycloak 공식 사이트](https://www.keycloak.org/downloads)에서 자신이 필요한 버전에 해당하는 압축 파일을 다운로드한다.
2. **압축 해제** 적절한 디렉토리에 압축을 풀고, 내부에 포함된 실행 스크립트를 확인한다.
3. **개발 모드 실행** 일반적으로 아래와 같은 명령어를 통해 Keycloak을 개발 모드로 실행할 수 있다.

   ```bash
   ./bin/kc.sh start-dev --http-port=8080
   ```

   또는

   ```bash
   ./bin/kc.bat start-dev --http-port=8080
   ```

   * `kc.sh` 또는 `kc.bat`은 Keycloak 실행 스크립트다.
   * `start-dev`: 개발 모드로 실행한다. 운영 환경에서는 DB 설정, HTTPS 설정 등 추가 구성 과정이 필요하다.
4. **관리자 계정 생성** 배포판으로 실행할 때도 관리자 계정 생성을 위한 환경 변수가 필요하다. 예를 들어 Linux나 macOS 환경에서는 다음과 같이 설정 후 실행한다.

   ```bash
   export KEYCLOAK_ADMIN=admin
   export KEYCLOAK_ADMIN_PASSWORD=admin123
   ./bin/kc.sh start-dev
   ```
5. **접속 확인** 웹 브라우저에서 `http://localhost:8080`으로 접속하면 Keycloak이 정상적으로 구동되고 있음을 확인할 수 있다. 이후 관리자 콘솔에서 로그인해 다양한 설정을 시도해볼 수 있다.

***

이상으로 Keycloak을 학습하기 위한 기본 환경을 구성하는 방법을 살펴보았다. 실제 운영 환경에서는 데이터베이스 연동, HTTPS 설정, 운영 모드 실행 등을 함께 고려해야 하지만, 학습 단계에서는 로컬 환경에서 빠르고 간단하게 Keycloak을 설치해 개념과 사용 방법을 익히는 것이 우선이다.

학습 환경 구성 후에는 Keycloak 관리 콘솔을 통해 Realm, Client, User, Role 등 주요 개념과 설정 방법에 익숙해지는 과정이 필요하다. 이를 위해 Keycloak 공식 문서를 참고하거나 예제 프로젝트를 직접 구성해보는 것을 권장한다.