9.2 KiB
9.2 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Keycloak — Running Keycloak in a container (server containers guide) | official-doc | https://www.keycloak.org/server/containers | raw | high |
|
|
|
2026-05-25 | 2026-05-27 |
Keycloak — Running Keycloak in a container
Layer:
raw/official-docs/— Keycloak 공식 Server Guides 의 컨테이너 운영 페이지 발췌. P3A docker-compose 시연 시quay.io/keycloak/keycloak이미지 +start-dev/KC_HOSTNAME/KC_HTTP_ENABLED설정 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-keycloak-patterns | Keycloak 운영 패턴 분류의 컨테이너 배포 변형 근거 |
| raw/branch-notes/feature-keycloak-single-ec2-no-google | P3A 단일 EC2 + docker compose 로 Keycloak 띄우는 방식의 출처 (quay.io/keycloak/keycloak, KC_HOSTNAME, start-dev vs start) |
| raw/branch-notes/feature-keycloak-docker-compose-stack | docker-compose 에서 Keycloak + Postgres 조합 시 KC_DB/KC_DB_URL 환경변수 사용 근거 |
| raw/branch-notes/feature-keycloak-https-termination-caddy-nginx | start-dev 의 insecure default 경고 → prod 진입 시 start (after build) 로 전환해야 한다는 공식 권고 출처 |
컨텍스트
P3A 단일 EC2 에서 docker compose 로 Keycloak + Postgres 를 띄우는 학습용 시연이 필요. 어떤 이미지 / 어떤 env / dev vs prod 모드의 차이가 출처가 되는 페이지.
출처 / Source
- 원본 URL: https://www.keycloak.org/server/containers
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — Server Guides
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27
- 이미지:
quay.io/keycloak/keycloak:<version>(예:26.6.2).
핵심 인용 / Key quotes (verbatim)
[§KC_HOSTNAME / --hostname] "Address at which is the server exposed. Can be a full URL, or just a hostname."
[§start-dev] "Invoking this command [
start-dev] starts the Keycloak server in development mode."
[§development mode warning] "This mode should be strictly avoided in production environments because it has insecure defaults."
[§production optimized build rationale] "containers need to be re-provisioned routinely"
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-CONTAINER-C1 | KC_HOSTNAME (= --hostname) 는 서버가 노출되는 주소이며 full URL 또는 hostname-only 형식 모두 허용 |
[§KC_HOSTNAME / --hostname] "Address at which is the server exposed. Can be a full URL, or just a hostname." | official-vendor-doc |
Keycloak Quarkus distribution 컨테이너 실행 시 환경변수 / CLI 옵션 | hostname-only 와 full URL 의 동작 차이 (scheme/port/path 의 동적 추출 정책 등) 디테일은 본 인용 범위 밖 — hostname guide 참조 |
| KC-CONTAINER-C2 | start-dev 명령은 Keycloak 서버를 development mode 로 실행한다 |
[§start-dev] "Invoking this command [start-dev] starts the Keycloak server in development mode." |
official-vendor-doc |
학습 / 로컬 / 데모 시나리오 | development mode 가 정확히 어떤 default 들을 비활성화/완화하는지의 전체 목록은 본 인용에 없음 |
| KC-CONTAINER-C3 | development mode 는 insecure default 를 가지므로 production 환경에서는 strictly avoided 되어야 한다 | [§development mode warning] "This mode should be strictly avoided in production environments because it has insecure defaults." | official-vendor-doc |
start-dev 로 띄운 Keycloak 인스턴스의 production 노출 결정 |
"insecure defaults" 의 구체 항목 (hostname-strict off, HTTP enabled by default, ephemeral admin 등) 의 enumeration 은 본 인용 범위 밖 |
| KC-CONTAINER-C4 | production 모드 optimized build 가 권장되는 이유 중 하나는 컨테이너가 routinely re-provisioned 되기 때문 | [§production optimized build rationale] "containers need to be re-provisioned routinely" | official-vendor-doc |
컨테이너 기반 prod 배포 (k8s rolling, ECS task replace 등) | 모든 prod 배포 방식이 routine re-provision 모델이라는 뜻은 아님 — long-running VM 배포에는 해당 안 될 수 있음 |
| KC-CONTAINER-C5 | KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD, KC_HTTP_ENABLED, KC_DB, 기본 포트 (HTTP 8080, HTTPS 8443, management/health 9000) 등의 구체적 값/이름은 본 raw 의 verbatim 발췌 범위에 직접 인용으로 포함되지 않음 — Keycloak 공식 문서 다른 섹션 / 환경변수 reference 일치로만 알려짐 |
(verbatim 부재 — 부재 자체가 claim) | needs-confirmation |
docker compose 시연에서 정확한 env name / default port 채택 | 해당 환경변수 / 포트가 틀렸다는 뜻은 아님. all-config / environment variables reference 페이지 직접 확인 권고 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
KC-CONTAINER-C1:KC_HOSTNAME의 입력 형식 (full URL or hostname)KC-CONTAINER-C2:start-dev의 의미 (development mode)KC-CONTAINER-C3: development mode 의 production 사용 금지 권고KC-CONTAINER-C4: optimized build 권장의 근거 (routine re-provision)
- 이 자료가 증명하지 않는 것:
KC-CONTAINER-C5: 환경변수 이름 / 기본 포트의 verbatim 출처 — 별도 환경변수 reference 페이지에서 보강 필요issclaim 이 hostname 과 어떻게 결합되는지 (hostname-v2 /keycloak-hostname-configuration참조)- postgres 외 다른 DB (mysql, mariadb 등) 의 정확한 JDBC URL 형식
- admin bootstrap 의 lifecycle (몇 번째 실행 후 무효화되는지)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- P3A 시연용 docker-compose 의 정확한 환경변수 (Admin UI 표시값 /
kc.sh show-config등으로 검증) start-dev로 띄운 인스턴스가 reverse proxy 뒤에서KC_PROXY_HEADERS=xforwarded와 결합될 때의 동작 (별도keycloak-reverseproxy-official참조)
- P3A 시연용 docker-compose 의 정확한 환경변수 (Admin UI 표시값 /
P3A 적용 메모 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아니라 P3A 운영 결정. wiki 추출 시
wiki/concepts/또는wiki/projects/로 옮겨야 함.
핵심 환경변수 / 옵션 (일반적으로 알려진 — needs-confirmation for verbatim)
KC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORD— 초기 admin 계정 부트스트랩.KC_HOSTNAME— 서버가 노출되는 주소. hostname 만 주면 scheme/port/path 는 요청에서 동적 추출 (별도 hostname guide 확인 필요).KC_HTTP_ENABLED=true— HTTP 허용 (학습/dev 한정, prod 권장 X).KC_DB— DB vendor (postgres,mysql,mariadb, ...).
실행 모드
| 모드 | 명령 | 용도 |
|---|---|---|
| Development | start-dev |
학습/로컬. insecure defaults (C3 경고 적용). |
| Production | start (after build) |
optimized image, prod 권장. |
Default Ports (verbatim 부재 — C5)
- HTTP:
8080 - HTTPS:
8443 - Management / Health:
9000
P3A 적용 메모
- P3A 시연용 docker-compose:
quay.io/keycloak/keycloak:26.x+start-dev+KC_HOSTNAME=localhost+KC_HTTP_ENABLED=true조합. - postgres 연결:
KC_DB=postgres,KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak,KC_DB_USERNAME/KC_DB_PASSWORD. - prod 진입 시 주의:
start-dev그대로 두면 hostname-strict 가 비활성화되어 fraudulent issuer 위험. raw/official-docs/keycloak-hostname-configuration 참조.
한계 / 후속
- 본 문서는 컨테이너 실행 방법만 다룸. issuer/hostname 디테일은 별도 hostname guide.
- 본 wiki 변환 시
wiki/concepts/keycloak-deployment-patterns또는wiki/projects/keycloak-patterns후보.
메모 / Notes
- 2026-05-27 재migration: WebFetch 권한 부재로 라이브 재검증 불가. 4건의 기존 verbatim 발췌 보존, 환경변수 이름 / 기본 포트는 명시적으로
needs-confirmation(C5). - 후속: all-config / environment variables reference 페이지 직접 발췌 후
C5분리하여 개별official-vendor-docclaim 으로 승격.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/keycloak-hostname-configuration —
KC_HOSTNAME동작 디테일 / issuer URL - raw/official-docs/keycloak-getting-started-docker — getting started 튜토리얼
- raw/official-docs/keycloak-reverseproxy-official — reverse proxy 환경 추가 설정
- raw/official-docs/keycloak-hostname-configuration —
- 인용하는 branch:
- 인용한 wiki: (미작성)