Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.2 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

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 페이지에서 보강 필요
- iss claim 이 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 적용 메모 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아니라 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-doc claim 으로 승격.

같은 주제 다른 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 환경 추가 설정
인용하는 branch:
인용한 wiki: (미작성)

9.2 KiB Raw Permalink Blame History