2. Docker start-dev (학습/검증)

Docker로 Keycloak start-dev 올리기 — 학습/검증 10분 컷

개요 — start-dev는 “학습/검증” 모드다. 운영은 start + DB + 프록시/TLS + hostname 설정으로 간다.

---

0) 오늘의 목표

• 컨테이너 한 방에 Keycloak 기동
• 관리자 계정 생성(bootstrap admin)
• 관리 콘솔 접속해서 Realm/Client 만들 준비

1) 가장 단순한 실행

아래는 “로컬/내부망 테스트”에 딱 좋은 형태다.

# 1) 이미지 내려받고
docker pull quay.io/keycloak/keycloak:26.4

# 2) 컨테이너 실행 (dev 모드)
docker run --name keycloak-dev --rm \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe-Now!' \
  quay.io/keycloak/keycloak:26.4 \
  start-dev

⚠️ start-dev는 운영용이 아니다.
- 단순 기동/학습에는 최고지만, 운영에서는 DB/HTTPS/프록시/hostname/백업/업그레이드 전략이 필요하다.

2) 접속 확인

# 브라우저:
http://localhost:8080

# Admin Console:
http://localhost:8080/admin

3) Realm을 파일로 Import하고 싶다면

테스트 환경에서 “미리 만든 Realm JSON”을 넣고 바로 띄우면 편하다.

# 예: ./realm-export.json 을 컨테이너로 마운트하고 import
docker run --name keycloak-dev --rm \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe-Now!' \
  -v "$PWD:/opt/keycloak/data/import" \
  quay.io/keycloak/keycloak:26.4 \
  start-dev --import-realm

---

다음 글 예고

TechNote 3에서 운영용 Compose(Postgres + optimized build + health/metrics)로 “진짜 운영 골격”을 잡아보자.

참고

• Keycloak Guides
• Server Container Image Guide