[Docker] Docker Compose를 이용한 Keycloak 환경 구성 및 실행 방법

해당 글에서는 Docker Compose를 통해서 Keycloak을 구성하는 방법에 대해 알아봅니다.

💡[참고] 이전에 작성한 Docker 관련 글들을 읽으시면 도움이 됩니다.

분류	설명	링크
이해하기	Docker 환경 설치 및 실행 방법	https://adjh54.tistory.com/350
이해하기	Docker 기초 이론(아키텍처, 흐름, 주요 용어)	https://adjh54.tistory.com/352
이해하기	Docker 컨테이너 라이프 사이클 & CLI	https://adjh54.tistory.com/359
이해하기	DockerFile 이론 + Nginx 환경 구성 및 배포 방법	https://adjh54.tistory.com/414
이해하기	Docker Compose 이해하고 구성	https://adjh54.tistory.com/503
환경구성	DockerFile + Vault 환경 구성 및 배포 방법	https://adjh54.tistory.com/415
환경구성	DockerFile + React 환경 구성 및 배포 방법	https://adjh54.tistory.com/417
환경구성	DockerFile + Spring Boot 환경 구성 및 배포 방법	https://adjh54.tistory.com/420
환경구성	DockerFile + Redis 환경 구성 및 배포 방법	https://adjh54.tistory.com/449
환경구성	DockerFile + RabbitMQ 환경 구성 및 실행 방법	https://adjh54.tistory.com/496
환경구성	Docker Compose + RabbitMQ 노드 클러스터링 방법	https://adjh54.tistory.com/517
환경구성	Docker Compose + Apache Kafka, Kafka-UI 환경 구성 방법	https://adjh54.tistory.com/637
환경구성	Docker Compose + Jenkins 환경 구성 및 실행방법	https://adjh54.tistory.com/643
환경구성	Docker Compose + Keycloak 환경 구성 및 실행방법	https://adjh54.tistory.com/644
이해하기	Keycloak 이해하기 -1 : 구성 요소, 인증 처리과정, 주요 기능	https://adjh54.tistory.com/645
이해하기	Keycloak 이해하기 -2 : SAML/OIDC 프로토콜, 인증 흐름(Authentication flow) 종류	https://adjh54.tistory.com/646
이해하기	Keycloak 이해하기 -3 : 기본 환경 구성 및 로그인/로그아웃 구현	https://adjh54.tistory.com/647
이해하기	Keycloak 이해하기 -4 : Keycloak 권한 및 종류	https://adjh54.tistory.com/655
환경파일	Dokcer Compose + Keycloak Dockerfile Repository	https://github.com/adjh54ir/multiflex-docker/tree/main/simple-docker-compose-keycloak

 
 

1) KeyCloak

---

💡 Keycloak

- Red Hat에서 개발한 오픈소스 Identity and Access Management(IAM) 솔루션입니다. 현대적인 애플리케이션과 서비스를 위한 인증 및 권한 부여 기능을 제공하는 인증 서버(Authentication Server)입니다

- Keycloack에서는 여러 플랫폼에서 중앙 집중식 인증 서버로 동작을 합니다.
- 주요한 기능은 서로 다른 도메인에서 실행되는 애플리케이션 간의 SSO를 지원하거나 REST API 기반에 접근제어 토큰에 대한 인증 제공 및 세션 타임아웃, 동시 로그인 제한과 같은 다양한 세션 기능을 담당합니다.

https://www.hcltech.com/blogs/keycloak-multitenancy

 

2) Dockerfile

---

💡 도커 파일(Dockerfile)

- 도커 이미지를 만들고 빌드하기 위한 ‘텍스트 파일’을 의미합니다. 이는 컨테이너 이미지를 구성하는데 필요한 모든 단계와 명령을 정의합니다.

 

1. Dockerfile 수행과정

---

💡 Dockerfile 수행과정

1. Dockerfile
- 도커파일에서 일련의 명령을 작성하여 이미지를 빌드하는 방법을 지정합니다. 또한 이미지를 지정하고 필요한 패키지를 설치하고 파일을 복사하여 명령을 실행하는 등의 작업을 수행합니다.

2. Dockerfile → (Build) → Docker Image
- 도커 엔진이 도커 파일을 한 줄씩 읽어서 이미지를 빌드합니다 : Dockerfile Layer

3. Docker Image → (Run) → Docker Container
- 빌드된 이미지를 실행하여 도커 컨테이너를 구성합니다.

 
 

3) Docker Compose

---

💡 Docker Compose

- 여러 컨테이너가 함께 실행되는 환경에서, 하나의 파일 내에 정의하여 여러 컨테이너를 관리하기 위한 도구를 의미합니다. 즉, 여러 컨테이너를 관리할 때, 단일 명령어를 통해 생성-관리-배포하는 기능을 수행하는 역할을 합니다.

- 기존의 Dockerfile을 통해 단일 컨테이너를 ‘생성-관리-배포’하는 과정에서의 처리과정은 간단하였으나 여러 컨테이너를 일괄 띄우는데 시간 소요가 많이 되기에 이를 사용합니다.
- 이러한 컨테이너 관리는 YAML 파일 형식을 사용하여 서비스, 네트워크 및 볼륨 같은 애플리케이션 서비스를 구성할 수 있습니다. 또한 개발, 테스트, 스테이징, 운영 및 CI 워크플로우 환경에서 애플리케이션을 이동하여 배포가 가능하기에 관리가 매우 편리합니다.

https://docs.docker.com/compose/

 
 

1. Docker Compose 처리 과정

---

💡 Docker Compose 처리 과정

1. Dockerfile에 필요한 모든 서비스를 정의합니다.(Define all your required services in a Dockerfile)
- Dockerfile 내에 각 다운로드 할 이미지와 실행 할 컨테이너에 대해 정의합니다.

2. Compose 파일(YAML/YML) 내에 각 서비스 간의 관계를 정의합니다.(Define the releationship between each service in a Compose file)
- 이 파일에는 실행할 서비스(컨테이너)들과 그 설정들을 포함하고 있습니다. 사용할 파일 내용은 Docker 이미지, 포트 매핑, 볼륨 마운트, 네트워크 설정, 환경 변수 등이 정의됩니다.

3. Docker Compose를 사용하여 애플리케이션을 시작합니다.(Use Docker Compose to start the application)
- Docker Compose의 실행 명령어 ‘docker-compose up’ 명령어를 수행하여 일괄 서비스를 실행합니다.
- 이 명령어를 통해서 Docker Compose 파일에 정의된 모든 서비스를 시작합니다.
- 필요한 Docker 이미지가 로컬에 없으면 자동으로 다운로드하고, 컨테이너를 생성하고 시작합니다.

4. Docker Compose의 서비스 상태를 확인합니다.
- Docker Compose의 상태 확인 명령어 ‘docker-compose ps’ 명령어를 수행하여 서비스의 상태를 확인합니다. 현재 실행 중인 서비스의 상태를 확인할 수 있습니다.

+ 필요에 따라 Docker Compose의 서비스를 중지합니다.
- Docker Compose의 중지 명령어 ‘docker-compose stop’ 명령어를 수행하거나 ‘docker-compose down’ 명령어를 수행하여 모든 서비스를 중지하고 컨테이너, 네트워크, 볼륨을 삭제합니다.

 
 

4) Docker 환경 구축 : 간단 구축 (DB 연결 없이)

---

💡 Docker 환경 구축 : 간단 구축 (DB 연결 없이)

- 데이터베이스 연결 없이 기본적인 KeyCloack 서버를 실행하는 방법을 구성해봅니다.
- 해당 경우에는 개발 모드(start-dev)로 실행되며, 개발 환경에 적합한 간단한 구성이 됩니다.
- ‘인메모리’ 내에 데이터가 저장이 되는 구조입니다. (* 컨테이너 재 실행 시 해당 값은 초기화됩니다.)

Docker - Keycloak

 

1. 실행방법 1: Quick Start 방법

---

💡 실행방법 1: Quick Start 방법

- 공식사이트에서 Docker를 기반으로 실행하는 방법을 알아봅니다.
- 로컬 포트 8080에 노출된 Keycloak을 시작하고, 사용자 이름과 비밀번호를 admin으로 사용하여 초기 관리자 사용자를 생성합니다

# Quick Start 실행
$ docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.1.0 start-dev

 
 

2. 실행방법 2: Docker file 구성 방법

---

💡 실행방법 2: Docker file 구성 방법

- 위에 와 동일한 구성이지만 Dockerfile 형태로 구성합니다.

FROM quay.io/keycloak/keycloak:26.1.0

ENV KC_BOOTSTRAP_ADMIN_USERNAME=admin
ENV KC_BOOTSTRAP_ADMIN_PASSWORD=admin

EXPOSE 8080

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]

# docker 컨테이너 이미지 생성
$ docker build -t simple-keycloak .

# docker 컨테이너 생성 및 실행
$ docker run -d -p 9001:8080 --name simple-keycloak simple-keycloak

# [필요 시] docker 컨테이너 중지
$ docker stop simple-keycloak

# [필요 시] docker 컨테이너 삭제 
$ docker rm simple-keycloak

 
 

3. 실행 결과

---

3.1. 컨테이너 이미지 다운 확인

---

 
 

3.2. 컨테이너 생성 확인

---

 
 
 

3.3. keycloak 접속 확인

---

💡 keycloak 접속 확인

- 지정한 http://localhost:9000 포트로 접근하였을 때, 잘 실행되고 ID/PW : admin으로 지정을 하였습니다.

 
 

5) Docker 환경 구축 : 상세 구축(DB 연결 포함)

---

💡 Docker 환경 구축 : 상세 구축(DB 연결 포함)

- 이전에 간단 연결을 통해 구성하면 ‘인메모리’ 내에 저장되었다가 컨테이너 재실행 시 값이 초기화되는 이유가 발생하였습니다.
- 그렇기에, 컨테이너가 재시작되거나 종료되어도 사용자 데이터 설정, 인증 정보 등을 유지하기 위해 데이터베이스와 연동을 하여 관리합니다.

 
 

💡 [참고] Keycloack 인증 서버를 데이터베이스와 사용해야 하는 점

장점	설명
데이터베이스 연동	PostgreSQL과 자동 연동되어 데이터를 안정적으로 저장하고 관리할 수 있습니다.
데이터 지속성	볼륨이 자동으로 구성되어 컨테이너가 재시작되어도 데이터가 유지됩니다.
설정 관리	환경 변수를 통해 각종 설정을 중앙에서 쉽게 관리하고 변경할 수 있습니다.
의존성 관리	서비스 간의 의존 관계가 자동으로 처리되어 안정적인 구동이 가능합니다.

 

 

1. Keycloak Dockerfile 구성

---

💡 Keycloak Dockerfile 구성

- 기본적인 Keycloak 구성 정보가 담긴 Dockerfile을 이용하여 이미지를 구성합니다.

FROM quay.io/keycloak/keycloak:26.1.0

ENV KC_BOOTSTRAP_ADMIN_USERNAME=admin
ENV KC_BOOTSTRAP_ADMIN_PASSWORD=admin

EXPOSE 8080

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev"]

 

 

2. Docker Compose 파일 구성

---

💡 Docker Compose 파일 구성

- keycloak 서비스와 postgresql을 실행하기 위한 서비스를 실행합니다.

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    ports:
      - "9001:8080"
    environment:
      - KC_BOOTSTRAP_ADMIN_USERNAME=admin
      - KC_BOOTSTRAP_ADMIN_PASSWORD=admin
      - KC_DB=postgres
      - KC_DB_URL=jdbc:postgresql://postgres:5432/testdb
      - KC_DB_USERNAME=localmaster
      - KC_DB_PASSWORD=qwer1234
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine3.21
    container_name: postgres
    environment:
      - POSTGRES_DB=testdb
      - POSTGRES_USER=localmaster
      - POSTGRES_PASSWORD=qwer1234
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

 

설정	설명
keycloak.image	Keycloak의 최신버전의 이미지를 받아옵니다.
keycloak.container_name	컨테이너의 이름 지정 (keycloak, postgres)
keycloak.ports	호스트의 9001 포트를 컨테이너의 8080 포트에 매핑
keycloak.KC_BOOTSTRAP_ADMIN_USERNAME	Keycloak 관리자 계정명 설정
keycloak.KC_BOOTSTRAP_ADMIN_PASSWORD	Keycloak 관리자 비밀번호 설정
keycloak.KC_DB	사용할 데이터베이스 종류 지정 (postgres)
keycloak.KC_DB_URL	PostgreSQL 데이터베이스 연결 URL
keycloak.KC_DB_USERNAME	데이터베이스 접속 사용자명
keycloak.KC_DB_PASSWORD	데이터베이스 접속 비밀번호
keycloak.depends_on	postgres 컨테이너가 먼저 실행되도록 의존성 설정
postgres.image	사용할 PostgreSQL 이미지 버전 지정
postgres.POSTGRES_DB	생성할 PostgreSQL 데이터베이스 이름
postgres.POSTGRES_USER	PostgreSQL 사용자 계정명
postgres.POSTGRES_PASSWORD	PostgreSQL 사용자 비밀번호
volumes	데이터 영속성을 위한 볼륨 설정

 
 

3. Docker Compose 실행 : Docker 이미지 생성 및 컨테이너 실행

---

💡 Docker Compose 실행 : Docker 이미지 생성 및 컨테이너 실행

- Docker 이미지 & 컨테이너를 실행하는 명령어를 통해 실행을 확인합니다.

# 프로젝트 접근
$ cd simple-docker-compose-keycloak

# docker 컨테이너 이미지 생성 & 컨테이너 실행
$ docker compose up -d

# docker compose 상태 확인
$ docker compose ps

# [필요시] 1. 실행 중인 컨테이너, 네트워크, 볼륨 모두 제거
$ docker compose down -v

# [필요시] 2. 이미지 제거 (선택사항)
$ docker rmi simple-keycloak postgres:16-alpine3.21
$ docker rmi simple-docker-compose-keycloak-keycloak:latest

# [필요시] 3. Docker Compose 다시 실행
$ docker compose up -d

 

💡 [참고] PostgreSQL 기반으로 로컬 데이터베이스 구성이 필요하시면 아래의 글을 참고하시면 도움이 됩니다.

[DB] MacOS에서 PostgreSQL 로컬 데이터베이스 구성 방법

 

4. 실행 결과

---

4.1. 컨테이너 이미지 확인

---

💡 컨테이너 이미지 확인

- 컨테이너 이미지가 정상적으로 받아짐을 확인하였습니다.

 
 

4.2. 컨테이너 상태 확인

---

💡 컨테이너 상태 확인

- Docker Compose 형태로 컨테이너가 생성되었고 실행됨을 확인하였습니다.

 
 

4.3. keycloak 접속 확인

---

 
 

4.4. Docker 내 postgresql 연동 확인

---

💡 Docker 내 postgresql 연동 확인

- Docker 내에 postgresql에 접근하여서 이를 확인하였습니다.

 
 

4.5. Keycloak 사용 테이블 확인

---

💡 Keycloak 사용 테이블 확인

- Keycloak에서 사용되는 테이블에 대해 확인해 봅니다.

# 예시: user_entity 테이블 구조 확인
$ \\d user_entity

# 예시: realm 테이블의 데이터 확인
$ SELECT id, name FROM realm;

테이블 명	설명
user_entity	사용자의 기본 정보와 프로필 데이터를 저장하는 테이블
client	Keycloak과 연동되는 클라이언트 애플리케이션의 설정 및 정보를 저장하는 테이블
realm	Keycloak의 보안 영역에 대한 설정과 구성 정보를 저장하는 테이블
user_role_mapping	사용자와 역할 간의 매핑 관계를 정의하는 테이블
authentication_flow	사용자 인증 과정의 단계와 흐름을 정의하는 테이블
credential	사용자의 비밀번호 및 기타 인증 관련 정보를 저장하는 테이블

 
 
 
 
오늘도 감사합니다. 😀