diff --git a/compose.ory.yaml b/compose.ory.yaml
index 1743a1c5..3a2bfd34 100644
--- a/compose.ory.yaml
+++ b/compose.ory.yaml
@@ -12,7 +12,11 @@ services:
     networks:
       - ory-net
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${ORY_POSTGRES_USER:-ory} -d ${KRATOS_DB:-ory_kratos}"]
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${ORY_POSTGRES_USER:-ory} -d ${KRATOS_DB:-ory_kratos}",
+        ]
       interval: 5s
       timeout: 5s
       retries: 5
@@ -91,7 +95,7 @@ services:
     image: oryd/hydra:${HYDRA_VERSION:-v25.4.0}
     environment:
       - DSN=postgres://${ORY_POSTGRES_USER}:${ORY_POSTGRES_PASSWORD}@postgres_ory:5432/${HYDRA_DB}?sslmode=disable&max_conns=20
-    command: migrate sql -e --yes
+    command: migrate sql up -e --yes
     depends_on:
       postgres_ory:
         condition: service_healthy
@@ -126,7 +130,7 @@ services:
       - DSN=postgres://${ORY_POSTGRES_USER}:${ORY_POSTGRES_PASSWORD}@postgres_ory:5432/${KETO_DB}?sslmode=disable&max_conns=20
     volumes:
       - ./docker/ory/keto:/etc/config/keto
-    command: migrate up -c /etc/config/keto/keto.yml --yes
+    command: ["migrate", "up", "-c", "/etc/config/keto/keto.yml", "--yes"]
     depends_on:
       postgres_ory:
         condition: service_healthy
diff --git a/docker/ory/keto/keto.yml b/docker/ory/keto/keto.yml
index 3f8023d1..d4521587 100644
--- a/docker/ory/keto/keto.yml
+++ b/docker/ory/keto/keto.yml
@@ -1,4 +1,5 @@
 version: v0.11.0
+dsn: ${DSN}
 serve:
   read:
     host: 0.0.0.0
@@ -6,7 +7,9 @@ serve:
   write:
     host: 0.0.0.0
     port: 4467
+
 namespaces:
   location: file:///etc/config/keto/namespaces.yml
+
 log:
   level: debug
diff --git a/docker/ory/keto/namespaces.yml b/docker/ory/keto/namespaces.yml
index 3b11865b..dca30db1 100644
--- a/docker/ory/keto/namespaces.yml
+++ b/docker/ory/keto/namespaces.yml
@@ -1,7 +1,6 @@
-namespaces:
-  - id: 0
-    name: default
-  - id: 1
-    name: roles
-  - id: 2
-    name: permissions
+- id: 0
+  name: default
+- id: 1
+  name: roles
+- id: 2
+  name: permissions
diff --git a/docs/compose-ory.md b/docs/compose-ory.md
new file mode 100644
index 00000000..57d98ad8
--- /dev/null
+++ b/docs/compose-ory.md
@@ -0,0 +1,154 @@
+## 서비스 역할
+
+### 1) `postgres_ory`
+
+- Ory 스택(Kratos/Hydra/Keto)이 공용으로 쓰는 PostgreSQL DB
+- `healthcheck`로 DB 준비 상태를 다른 서비스들이 기다릴 수 있게 함
+
+### 2) `kratos-migrate`
+
+- Kratos DB 스키마 마이그레이션을 수행하는 1회성 컨테이너
+- Postgres가 healthy가 된 뒤에 실행되고, 성공해야 Kratos가 뜸
+
+### 3) `kratos`
+
+- **인증/회원(Identity) 담당**: 로그인/회원가입/리커버리/검증 등 Self-service flow 제공
+- 포트
+  - `4433`(public): 브라우저/클라이언트가 접근하는 API
+  - `4434`(admin): 관리용 API(내부에서만 쓰는 게 일반적)
+
+- `--watch-courier`는 이메일/메시지 발송 관련(개발 모드) 흐름을 돕는 옵션
+
+### 4) `kratos-mcp-server` (현재는 `profiles: mcp`)
+
+- Kratos Admin API를 대신 호출해주는 “자동화/툴링(LLM 연동 포함) 브리지”
+- 사람/브라우저가 직접 쓰는 서비스라기보다, 내부 도구가 붙어서 identity 관리 작업을 자동화할 때 사용
+
+### 5) `kratos-ui`
+
+- Kratos의 로그인/회원가입 등 Self-service 화면을 제공하는 UI 서버
+- Kratos public/admin URL을 환경변수로 받아서 UI가 Kratos와 통신함
+
+---
+
+### 6) `hydra-migrate`
+
+- Hydra DB 스키마 마이그레이션을 수행하는 1회성 컨테이너
+- Postgres가 healthy가 된 뒤 실행되고, 성공해야 Hydra가 뜸
+
+### 7) `hydra`
+
+- **OAuth2 / OIDC Provider**: authorization code 발급, access/refresh token 발급 등
+- 포트
+  - `4444`(public): authorization/token/jwks 등 외부 클라이언트가 접근
+  - `4445`(admin): 클라이언트 등록/관리 등 관리자 API
+
+- `URLS_SELF_ISSUER`, `URLS_LOGIN`, `URLS_CONSENT`로 “로그인/동의 화면을 어디서 처리할지”를 외부(backend)로 위임
+
+### 8) `hydra-mcp-server` (지금은 profiles 제거되어 항상 뜸)
+
+- Hydra Admin/Public API를 대신 호출해주는 “자동화/툴링(LLM 연동 포함) 브리지”
+- 주 용도는 OAuth 클라이언트 생성/수정/조회 자동화, 테스트 환경 세팅, 운영 자동화 등
+- 브라우저로 접속하는 포트 서비스가 아닐 가능성이 높고(ports 없음), 내부 도구가 붙어서 사용
+
+---
+
+### 9) `keto-migrate`
+
+- Keto(권한/관계 기반 접근제어) DB 마이그레이션 수행 1회성 컨테이너
+- Postgres가 healthy가 된 뒤 실행되고, 성공해야 Keto가 뜸
+
+### 10) `keto`
+
+- **권한/정책(관계 튜플) 기반 접근제어** 담당(Ory Keto)
+- 포트
+  - `4466` read API
+  - `4467` write API
+
+- “누가 어떤 리소스에 어떤 관계/권한이 있는지”를 저장/조회하는 역할
+
+---
+
+### 11) `oathkeeper`
+
+- **Reverse proxy + Access rule enforcement**(인증/인가 게이트웨이)
+- 일반적으로 앞단에서 요청을 받아서 “인증 여부 확인 후” 백엔드로 프록시
+- 포트
+  - `4456` API(관리/디버그용으로 쓰는 경우 많음)
+  - `4455` Proxy(외부 트래픽이 통과하는 포트로 쓰는 경우가 많음)
+
+---
+
+### 12) `ory_stack_check`
+
+- 알파인에서 curl로 Kratos/Hydra/Keto의 `/health/ready`를 폴링해서 “스택 준비 완료”를 확인하는 헬퍼
+- 준비가 끝나야 다음 단계(init-rp)가 안전하게 실행됨
+
+### 13) `init-rp`
+
+- Hydra Admin API로 **OAuth 클라이언트(Relying Party)를 자동 등록**하는 1회성 컨테이너
+- 여기서는 `adminfront`, `devfront` 클라이언트를 만들어 둠
+- 실제 서비스 시작 시 “클라이언트가 없어서 로그인 플로우가 안 되는” 문제를 방지
+
+---
+
+## 네트워크 역할
+
+### `ory-net` (external)
+
+- Postgres/Kratos/Hydra/Keto/Oathkeeper 등 Ory 스택 내부 서비스들이 서로 통신하는 공용 네트워크
+- `http://hydra:4445`, `http://kratos:4434` 같은 서비스 디스커버리가 여기서 성립
+
+### `hydranet` (external)
+
+- Hydra가 붙는 별도 네트워크
+- `init-rp`가 `hydranet`에 붙어서 Hydra Admin API로 클라이언트 등록을 수행
+
+### `kratosnet` (external)
+
+- Kratos가 붙는 별도 네트워크
+- 다른 애플리케이션(예: backend)이 Kratos와 통신할 때 분리된 네트워크로 구성하는 패턴
+
+---
+
+## 볼륨 역할
+
+### `ory_postgres_data`
+
+- Postgres 데이터 영속화(컨테이너 재시작/재생성해도 DB 유지)
+
+---
+
+## 확인할 서비스
+
+### Kratos:
+
+```
+curl -i http://localhost:4433/health/ready
+```
+
+### Hydra:
+
+```
+curl -i http://localhost:4441/health/ready
+```
+
+### Keto:
+
+```
+curl -i http://localhost:4466/health/ready
+```
+
+### Oathkeeper:
+
+```
+curl -i http://localhost:4456/health/ready
+```
+
+### 화면이 떠야 하는 것 (UI)
+
+```
+http://localhost:4455/... : Kratos UI (이미 OK)
+
+http://localhost:5000, http://localhost:5174 : 프론트들 (이미 OK)
+```