llm-wiki/raw/official-docs/keycloak-getting-started-docker.md

---
title: Keycloak — Get started with Keycloak on Docker (quickstart)
source_type: official-doc
url: https://www.keycloak.org/getting-started/getting-started-docker
archive_url:
status: raw
confidence: high
tags: [keycloak, keycloak-patterns, p3a-single-ec2, docker, quickstart, realm, client, redirect-uri]
related_projects: [keycloak-patterns]
related_branches: [feature-keycloak-patterns, feature-keycloak-single-ec2-no-google, feature-keycloak-docker-compose-stack, feature-keycloak-realm-client-export]
created: 2026-05-25
last_reviewed: 2026-05-27
---

# Keycloak — Getting started on Docker (quickstart)

> Layer: `raw/official-docs/` — Keycloak quickstart 가이드 발췌. P3A 단일 EC2 학습 환경의 docker 기반 booting 절차의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-patterns]] | keycloak-patterns root — 최소 booting 방법으로 `start-dev` + docker 채택 근거 |
| [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] | P3A 단일 EC2 학습 환경에서 quickstart docker 명령으로 초기 부팅 결정 근거 |
| [[raw/branch-notes/feature-keycloak-docker-compose-stack]] | docker-compose 로 동일 부팅 정보 (KC_BOOTSTRAP_ADMIN_* env, port 8080) 를 확장 |
| [[raw/branch-notes/feature-keycloak-realm-client-export]] | realm/client 생성 절차의 admin console 경로 + Partial export 의 baseline 사실 |

## 컨텍스트

Keycloak 의 학습용 quickstart. **production 용 아님** — `start-dev` 옵션은 명시적으로 dev 모드. P3A 단일 EC2 학습 환경에서 booting + realm/client 생성을 한 번에 시연.

## 출처 / Source

- 원본 URL: https://www.keycloak.org/getting-started/getting-started-docker
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat)
- 발행일: rolling docs (current = 26.x)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Start Keycloak] "docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.2 start-dev"

> [§Start Keycloak] "This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username `admin` and password `admin`."

> [§Create a realm] "A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users."

> [§Secure the first application] "Set **Valid redirect URIs** to `https://www.keycloak.org/app/*`"

> [§Secure the first application] "Set **Web origins** to `https://www.keycloak.org`"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-GSD-C1 | quickstart docker 명령은 `quay.io/keycloak/keycloak:26.6.2 start-dev` 이미지를 `KC_BOOTSTRAP_ADMIN_USERNAME=admin` + `KC_BOOTSTRAP_ADMIN_PASSWORD=admin` env 와 함께 `127.0.0.1:8080:8080` 으로 노출 | [§Start Keycloak] "docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.2 start-dev" | `official-vendor-doc` | quickstart / 학습 환경 booting | production 사용을 권장한다는 뜻은 아님 — `start-dev` 명시 |
| KC-GSD-C2 | 위 명령은 Keycloak 을 local 8080 포트로 노출하고 username/password = `admin/admin` 의 초기 admin user 를 생성 | [§Start Keycloak] "This command starts Keycloak exposed on the local port 8080 and creates an initial admin user with the username `admin` and password `admin`." | `official-vendor-doc` | 첫 booting 시점 | admin password 를 그대로 두고 production 운영해도 된다는 뜻 아님 — quickstart 한정 |
| KC-GSD-C3 | Keycloak 의 realm = tenant. 각 realm 은 application/user 의 isolated group 을 제공 | [§Create a realm] "A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users." | `official-vendor-doc` | Keycloak multi-tenancy 모델 일반 | realm 간 cross-realm trust 또는 federation 의 디테일은 본 인용 범위 밖 |
| KC-GSD-C4 | Client 등록 시 `Valid redirect URIs` 와 `Web origins` 는 정확한 URI/origin 값으로 설정 (quickstart 예시: `https://www.keycloak.org/app/*` + `https://www.keycloak.org`) | [§Secure the first application] "Set **Valid redirect URIs** to `https://www.keycloak.org/app/*`" + "Set **Web origins** to `https://www.keycloak.org`" | `official-vendor-doc` | OIDC public client (SPA) 등록 시 redirect_uri + CORS 정책 | wildcard `/*` 매칭의 정확한 보안 영향 / SPA path-level 매칭 규칙은 본 인용에 없음 — 별도 ` keycloak-google-redirect-uri-policy.md` 참조 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `KC-GSD-C1` ~ `C4`: 학습용 quickstart 의 docker 명령, realm 정의, client 등록 시 redirect_uri/web origins 의 정확한 값 형식
- **이 자료가 증명하지 않는 것**:
  - production deployment 의 hardening 절차 (별도 `keycloak-server-containers-docker.md`, `keycloak-hostname-configuration.md`, `keycloak-reverseproxy-official.md` 참조)
  - `start-dev` vs `start` 모드의 정확한 차이 (production-ready 전환 시 변경되는 default)
  - realm export/import JSON 의 schema (별도 페이지)
  - PKCE / Standard Flow 강제 토글의 정확한 위치 (Advanced settings 의 정확한 label)
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - P3A 의 redirect_uri 가 `http://localhost/callback` (localhost+path) 인지 `http://<ec2-ip>:8080/callback` 인지에 따라 client 등록 값 결정
  - `--import-realm` 옵션의 정확한 명령 위치 (`docker run ... start-dev --import-realm` 형태인지)
  - admin 초기 password 를 rotate 하는 권장 명령

## quickstart 명령 (인용 그대로)

```bash
docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.6.2 start-dev
```

## Realm/Client 생성 절차 (페이지 기준 요약)

1. http://localhost:8080/admin 접속 (admin/admin 로그인).
2. 좌측 컬럼 "Manage realms" 클릭.
3. "Create realm" 선택. 이름 입력 (예: `myrealm` → P3A 에서는 `keycloak-patterns`).
4. "Clients" 섹션에서 "Create client".
   - Client type: `OpenID Connect`
   - Client ID: `myclient` (P3A 에서는 `spa-client`)
5. Login settings:
   - `Valid redirect URIs`: quickstart 예시는 `https://www.keycloak.org/app/*` — P3A 는 실제 SPA callback 으로 변경
   - `Web origins`: quickstart 예시는 `https://www.keycloak.org` — P3A 는 실제 SPA origin
6. Save.

## P3A 적용 메모 (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. P3A 결정 컨텍스트 해석.

- Client type **public** + **Standard Flow + PKCE S256** 강제 (Advanced settings → `Proof Key for Code Exchange Code Challenge Method = S256`).
- **redirect_uri 정확 매칭**: `http://localhost/callback` ≠ `http://127.0.0.1/callback` ≠ `http://<ec2-ip>/callback`. SPA 가 사용하는 URI 와 한 글자도 다르면 안 됨.
- realm export: 관리 콘솔 → Realm settings → Action → Partial export → JSON 다운로드. `keycloak-patterns-realm.json` 으로 commit 하면 docker-compose 에서 `--import-realm` 옵션으로 자동 임포트 가능 (정확한 명령 형식은 별도 확인).

## 한계 / 후속

- 본 문서는 quickstart. production hardening, HA, clustering 은 별도 가이드.
- 본 wiki 변환 시 `wiki/projects/keycloak-patterns` (P3A 구현 후) 후보.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/keycloak-server-containers-docker]] (production-grade container 운영)
  - [[raw/official-docs/keycloak-hostname-configuration]]
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-patterns]]
  - [[raw/branch-notes/feature-keycloak-single-ec2-no-google]]
  - [[raw/branch-notes/feature-keycloak-docker-compose-stack]]
- 인용하는 wiki: (미작성)