Docker를 이용한 설치

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

1. Docker 환경 준비

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

• Docker 설치 여부 확인:

  docker --version

  버전 정보가 출력되면 Docker가 정상적으로 설치된 상태다.

• Docker 미설치 시:

  • Linux(예: Ubuntu) 환경이라면 다음 명령으로 설치 가능하다.

    sudo apt-get update
    sudo apt-get install -y docker.io

  • Windows 및 macOS 환경에서는 Docker 공식 사이트에서 Docker Desktop을 다운로드 및 설치한다.

2. Keycloak 이미지 받기

Keycloak 공식 이미지는 quay.io/keycloak/keycloak 저장소에서 제공된다.

• 최신 버전 이미지 받기:

  docker pull quay.io/keycloak/keycloak:latest

• 특정 버전 이미지를 사용하려면 :latest 대신 특정 태그(예: :21.1.0)를 지정한다.

3. Keycloak 컨테이너 실행

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

• 간단 실행 예시:

  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 사용 시):

  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

• 볼륨 마운트 예시:

  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) 등을 종합적으로 고려해야 한다.