129 lines
9.2 KiB
Markdown
129 lines
9.2 KiB
Markdown
---
|
|
title: Keycloak — Running Keycloak in a container (server containers guide)
|
|
source_type: official-doc
|
|
url: https://www.keycloak.org/server/containers
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [keycloak, keycloak-patterns, p3a-single-ec2, docker, docker-compose, container, hostname, jwt-validation]
|
|
related_projects: [keycloak-patterns]
|
|
related_branches: [feature-keycloak-patterns, feature-keycloak-single-ec2-no-google, feature-keycloak-docker-compose-stack, feature-keycloak-https-termination-caddy-nginx]
|
|
created: 2026-05-25
|
|
last_reviewed: 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 페이지에서 보강 필요
|
|
- `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 으로 승격.
|
|
|
|
## 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 환경 추가 설정
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-keycloak-patterns]]
|
|
- [[raw/branch-notes/feature-keycloak-single-ec2-no-google]]
|
|
- [[raw/branch-notes/feature-keycloak-docker-compose-stack]]
|
|
- [[raw/branch-notes/feature-keycloak-https-termination-caddy-nginx]]
|
|
- 인용한 wiki: (미작성)
|