109 lines
11 KiB
Markdown
109 lines
11 KiB
Markdown
---
|
|
title: Caddy — Automatic HTTPS (official-vendor-doc)
|
|
source_type: official-doc
|
|
url: https://caddyserver.com/docs/automatic-https
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [caddy, https, tls, acme, lets-encrypt, on-demand-tls, keycloak-https-termination]
|
|
related_projects: []
|
|
related_branches: [feature-keycloak-https-termination-caddy-nginx]
|
|
created: 2026-05-27
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# 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 설정 검증 필요.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 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]]
|