baron-sso/docs/compose-ory.md

서비스 역할

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)