# Docker를 이용한 설치

Keycloak을 Docker 컨테이너로 실행하면 빠른 배포와 버전 관리를 손쉽게 수행할 수 있다. 다음은 Keycloak 공식 Docker 이미지를 활용해 설치 및 실행하는 방법을 단계별로 정리한 것이다.

#### 1. Docker 환경 준비

Keycloak을 Docker로 실행하려면 Docker가 사전에 설치되어 있어야 한다.

* Docker 설치 여부 확인:

  ```bash
  docker --version
  ```

  버전 정보가 출력되면 Docker가 정상적으로 설치된 상태다.
* Docker 미설치 시:
  * Linux(예: Ubuntu) 환경이라면 다음 명령으로 설치 가능하다.

    ```bash
    sudo apt-get update
    sudo apt-get install -y docker.io
    ```
  * Windows 및 macOS 환경에서는 [Docker 공식 사이트](https://www.docker.com/products/docker-desktop/)에서 Docker Desktop을 다운로드 및 설치한다.

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

Keycloak 공식 이미지는 [quay.io/keycloak/keycloak](https://quay.io/repository/keycloak/keycloak) 저장소에서 제공된다.

* 최신 버전 이미지 받기:

  ```bash
  docker pull quay.io/keycloak/keycloak:latest
  ```
* 특정 버전 이미지를 사용하려면 `:latest` 대신 특정 태그(예: `:21.1.0`)를 지정한다.

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

Keycloak 최신 버전(17 이상)에서는 `start-dev` 명령을 활용해 개발(테스트) 환경용 서버를 빠르게 실행할 수 있다.

* 간단 실행 예시:

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

  * `--name keycloak` : 컨테이너 이름을 `keycloak`으로 지정한다.
  * `-p 8080:8080` : 호스트의 8080 포트를 Keycloak 컨테이너의 8080 포트에 연결한다.
  * `-e KEYCLOAK_ADMIN=admin` : 관리자 계정 이름을 `admin`으로 설정한다.
  * `-e KEYCLOAK_ADMIN_PASSWORD=admin` : 관리자 계정 비밀번호를 `admin`으로 설정한다.
  * `start-dev` : 개발 모드로 Keycloak 서버를 시작한다.

#### 4. 실행 확인 및 초기 설정

* **로그 확인**: 컨테이너 실행 후 터미널에 출력되는 로그를 통해 서버가 정상적으로 기동되었는지 확인한다.
* 관리 콘솔 접속:

  웹 브라우저에서

  ```
  http://<호스트 IP>:8080
  ```

  으로 접속한다.

  * 기본 화면에서 “Administration Console” 버튼을 눌러 관리 콘솔로 이동한다.
  * 위에서 설정한 관리자 계정(`admin`)과 비밀번호(`admin`)로 로그인한다.

#### 5. 지속적 데이터 보존(선택 사항)

기본적으로 컨테이너가 종료되면 내부 데이터(내장 H2 DB 사용 시)는 함께 사라진다. 운영 환경에서는 외부 DB 또는 볼륨 마운트를 통한 데이터 보존이 필요하다.

* 외부 DB 연동 예시

  (PostgreSQL 사용 시):

  ```bash
  docker run --name keycloak \
    -p 8080:8080 \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    -e KC_DB=postgres \
    -e KC_DB_URL_HOST=<postgres-host> \
    -e KC_DB_URL_DATABASE=<database-name> \
    -e KC_DB_USERNAME=<db-username> \
    -e KC_DB_PASSWORD=<db-password> \
    quay.io/keycloak/keycloak:latest start-dev
  ```
* 볼륨 마운트 예시:

  ```bash
  docker run --name keycloak \
    -p 8080:8080 \
    -v /my/local/path/keycloak-data:/opt/keycloak/data \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    quay.io/keycloak/keycloak:latest start-dev
  ```

  * `/my/local/path/keycloak-data` 디렉터리에 Keycloak 데이터가 보존되므로 컨테이너 재시작 후에도 설정 및 DB 데이터가 유지된다.

#### 6. 운영 환경 고려 사항

* **HTTPS 설정**: 운영 환경에서는 SSL이 필수적이다. 개발 모드(`start-dev`) 대신 별도의 설정(트러스트스토어, 인증서 등)이 필요하다.
* **고가용성/부하 분산 구성**: Keycloak 클러스터나 프록시(예: NGINX, HAProxy) 구성을 통해 부하 분산과 고가용성을 확보할 수 있다.
* **모니터링**: 컨테이너 오케스트레이션 툴(예: Kubernetes)이나 Prometheus, Grafana 등을 통해 시스템 모니터링 및 로그 관리를 수행한다.

이상과 같은 과정을 통해 Docker 환경에서 Keycloak을 쉽게 설치하고 테스트할 수 있다. 운영 환경에 적용할 경우에는 외부 DB 및 보안 설정(HTTPS) 등을 종합적으로 고려해야 한다.