Files

T

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

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

11 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

Caddy — Automatic HTTPS (공식)

Layer: raw/official-docs/ — Caddy 공식 문서의 원문 발췌·출처 기록. Strength 분류: official-vendor-doc — Caddy 의 공식 documentation site (caddyserver.com/docs/...). 검증된 요약은 /ingest 후 wiki/concepts/ 에 별도 작성.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-https-termination-caddy-nginx	D2 (Caddy auto-HTTPS + Let's Encrypt) 의 근거 — Caddy 가 ACME (Let's Encrypt / ZeroSSL) 로 자동 certificate 발급·갱신 + HTTP→HTTPS redirect 를 default 동작으로 보장. nginx + certbot 대비 운영 단순성의 외부 근거.

컨텍스트

feature-keycloak-https-termination-caddy-nginx 의 D2 는 "Keycloak 앞단 TLS 종단을 Caddy 로 처리한다" 는 결정을 다룬다. Caddy 의 Automatic HTTPS 페이지는 (a) 도메인 인식 시 ACME 자동 발급, (b) HTTP→HTTPS redirect, (c) renewal in background 를 직접 진술한다. 본 raw 는 D2 의 외부 근거로 보관.

출처 / Source

원본 URL: https://caddyserver.com/docs/automatic-https
아카이브 URL: (미수집 — 추후 archive.org 스냅샷 추가)
저자 / 조직: Caddy / Stack Holdings — Caddy official documentation
발행일: rolling docs (Caddy 2.x current)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Overview] "Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed."

[§Overview] "By default, Caddy serves all sites over HTTPS."

[§Overview] "Caddy was the first web server to use HTTPS automatically and by default."

[§Overview] "Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as Let's Encrypt or ZeroSSL."

[§Overview] "Caddy keeps all managed certificates renewed and redirects HTTP (default port 80) to HTTPS (default port 443) automatically."

[§Overview] "It will not get certificates for individual subdomains unless explicitly configured to do so; and renewals happen in the background."

[§Activation] "Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) or IP address it is serving."

[§Activation] "Explicitly disabling it via JSON or via Caddyfile will prevent automatic HTTPS from being activated, either in whole or in part."

[§Storage] "Caddy will store public certificates, private keys, and other assets in its configured storage facility"

[§Storage] "The main thing you need to know using the default config is that the $HOME folder must be writeable and persistent."

[§On-Demand TLS] "On-demand TLS is useful if: you do not know all the domain names when you start or reload your server"

[§On-Demand TLS] "when a TLS handshake is received for a server name (SNI) that Caddy does not yet have a certificate for, the handshake is held while Caddy obtains a certificate"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
CADDY-AHTTPS-C1	Caddy 의 Automatic HTTPS 는 TLS certificate 자동 발급 + 자동 갱신 을 모든 site 에 대해 수행	[§Overview] "Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed."	`official-vendor-doc`	Caddy 2.x 에서 도메인 명시 설정 시	"모든 종류의 CA 와 호환" 이라는 뜻은 아님 — 본 인용 다음 줄에서 ACME CA 한정 (`C3` 참조)
CADDY-AHTTPS-C2	Caddy 는 default 로 모든 site 를 HTTPS 로 serve 하며, HTTPS by default 를 채택한 최초의 web server 라고 주장	[§Overview] "By default, Caddy serves all sites over HTTPS." + "Caddy was the first web server to use HTTPS automatically and by default."	`official-vendor-doc`	Caddy 의 default 동작	"다른 web server 가 HTTPS by default 가 아니다" 라는 비교 진술은 본 인용으로 일반화 금지 (nginx 1.25+ 등은 별도 확인)
CADDY-AHTTPS-C3	Caddy 는 public DNS name 의 HTTPS 를 public ACME CA (Let's Encrypt 또는 ZeroSSL) 의 certificate 로 처리	[§Overview] "Caddy serves public DNS names over HTTPS using certificates from a public ACME CA such as Let's Encrypt or ZeroSSL."	`official-vendor-doc`	public DNS 도메인을 가진 site	internal domain / private CA 사용 시에는 별도 설정 필요 (본 인용 범위 밖)
CADDY-AHTTPS-C4	Caddy 는 HTTP (port 80) → HTTPS (port 443) redirect 를 자동 수행 + managed cert 자동 갱신	[§Overview] "Caddy keeps all managed certificates renewed and redirects HTTP (default port 80) to HTTPS (default port 443) automatically."	`official-vendor-doc`	default Caddyfile 설정 사용 시	redirect 의 HTTP status code (301 vs 308) 는 본 인용 범위 밖
CADDY-AHTTPS-C5	Caddy 는 개별 subdomain 에 대해서는 자동 발급하지 않으며 (명시 설정 필요), renewal 은 background 에서 수행	[§Overview] "It will not get certificates for individual subdomains unless explicitly configured to do so; and renewals happen in the background."	`official-vendor-doc`	wildcard / subdomain 인증서 정책	renewal 의 정확한 주기 (예: "30일 전") 는 본 인용 범위 밖 — 별도 ACME issuer 정책 의존
CADDY-AHTTPS-C6	Automatic HTTPS 는 Caddy 가 serve 하는 hostname 또는 IP 를 인식하면 암묵적으로 활성화	[§Activation] "Caddy implicitly activates automatic HTTPS when it knows a domain name (i.e. hostname) or IP address it is serving."	`official-vendor-doc`	Caddyfile / JSON 에 명시된 hostname/IP	"IP address 인 경우 ACME 가 발급한다" 는 뜻은 아님 — IP 에 대한 public CA 발급은 제한적
CADDY-AHTTPS-C7	JSON 또는 Caddyfile 에서 명시적으로 disable 가능 (전체 또는 부분)	[§Activation] "Explicitly disabling it via JSON or via Caddyfile will prevent automatic HTTPS from being activated, either in whole or in part."	`official-vendor-doc`	Automatic HTTPS opt-out 시나리오	opt-out 의 구체적 directive 명 (`auto_https off` 등) 은 본 인용 범위 밖 — 별도 Caddyfile reference 참조
CADDY-AHTTPS-C8	인증서/키 등 자산은 configured storage facility 에 저장, default config 에서는 `$HOME` 이 writable + persistent 여야 함	[§Storage] "Caddy will store public certificates, private keys, and other assets in its configured storage facility" + "the `$HOME` folder must be writeable and persistent."	`official-vendor-doc`	container / systemd 환경에서 Caddy 운영	container 환경에서 `$HOME` 의 default 가 어디인지는 본 인용 범위 밖 — Docker image 별 확인
CADDY-AHTTPS-C9	On-Demand TLS 는 시작/reload 시점에 모든 domain 을 알 수 없는 경우 유용	[§On-Demand TLS] "On-demand TLS is useful if: you do not know all the domain names when you start or reload your server"	`official-vendor-doc`	multi-tenant / wildcard SaaS 시나리오	on-demand TLS 가 production default 라는 뜻은 아님 — opt-in 기능
CADDY-AHTTPS-C10	On-Demand TLS 는 알려지지 않은 SNI 의 handshake 도래 시 handshake 를 보류 하고 cert 를 obtain	[§On-Demand TLS] "when a TLS handshake is received for a server name (SNI) that Caddy does not yet have a certificate for, the handshake is held while Caddy obtains a certificate"	`official-vendor-doc`	on-demand TLS 활성화 시	handshake 보류의 timeout / DoS 방지 메커니즘은 본 인용 범위 밖 — 별도 on-demand TLS 페이지 참조
CADDY-AHTTPS-C11	HSTS (Strict-Transport-Security) 관련 직접 진술은 본 페이지에 부재 — 부재 사실 자체가 claim	(인용 없음 — 본 페이지에서 HSTS 미언급)	`needs-confirmation`	HSTS default behavior 주장 시	Caddy 가 HSTS 를 default 로 보내지 않는다는 뜻이 아님. 단지 본 페이지가 보증하지 않는다는 사실. D2 의 "HSTS defaults" 주장은 본 raw 로 입증 불가 — `tls` directive 또는 별도 페이지 확인 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- CADDY-AHTTPS-C1, C3, C4, C5: ACME 자동 발급 + HTTP→HTTPS redirect + background renewal 가 Caddy 의 default 동작
- CADDY-AHTTPS-C6, C7: 활성화/비활성화 트리거 (hostname 인식 / 명시 disable)
- CADDY-AHTTPS-C8: storage 요구사항 ($HOME writable + persistent)
이 자료가 증명하지 않는 것:
- HSTS 자동 적용 — 본 페이지에 HSTS 직접 언급 없음 (C11). D2 에서 "HSTS defaults" 를 주장하려면 별도 출처 필요 (예: Caddy tls directive 문서, header 전역 directive 문서)
- certificate renewal 의 정확한 timing (예: "만료 30일 전") — C5 는 "background 에서 renewal" 만 진술
- ZeroSSL fallback 의 발생 조건 — C3 은 "such as Let's Encrypt or ZeroSSL" 만 진술, 선택 로직은 본 인용 범위 밖
- nginx + certbot 대비 운영 우위 — Caddy 문서는 자기 동작만 진술, 비교 결론은 별도 분석 필요
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- feature-keycloak-https-termination-caddy-nginx 의 D2 에서 HSTS 보장 을 명시하려면 본 raw 외 추가 출처 필요 (Caddy tls 또는 header directive 문서 + 실제 response header 검증)
- Keycloak KC_PROXY_HEADERS=xforwarded 와 Caddy 의 default proxy header 동작 호환성 — 본 raw 는 reverse proxy header 명세까지 다루지 않음 (별도 Caddy reverse_proxy directive 문서 필요)
- Let's Encrypt 의 rate limit (per-domain 주당 50건 등) — 본 raw 범위 밖, Let's Encrypt 공식 문서 참조

메모 / Notes

C11 은 중요한 부재 사실. D2 의 "HSTS defaults" 주장을 본 raw 로 정당화하면 UNSUPPORTED_DECISION 으로 분류되어야 함. 별도 출처 보강 필수.
C2 의 "first web server to use HTTPS automatically and by default" 는 historical 주장 — 다른 server (nginx 1.25, Apache 2.4 등) 와의 비교는 본 인용으로 일반화 금지.
container 환경에서 Caddy 운영 시 $HOME (C8) 가 read-only FS 면 동작 실패 — Dockerfile / k8s volume 설정 검증 필요.

같은 주제 다른 raw 자료: raw/official-docs/certbot-user-guide.md (nginx + certbot 대안)
이 자료를 인용한 wiki 요약: (미작성)
이 자료를 인용하는 branch: raw/branch-notes/feature-keycloak-https-termination-caddy-nginx
인용하는 project: raw/project-notes/keycloak-patterns-overview

11 KiB Raw Permalink Blame History