Caddy Config

Caddyfile과 native JSON 구성에서 자주 확인하는 기본 구조, 핵심 directive, 검증 절차를 정리한다.

• 사람이 직접 편집할 때는 보통 Caddyfile 을 사용한다.
• Caddyfile은 site address 다음에 directive를 나열하는 구조라서 NGINX보다 짧게 작성되는 편이다.
• 설정 반영 전에는 caddy fmt, caddy adapt, caddy validate 를 순서대로 점검하면 안전하다.

• 사이트 주소 또는 global options block으로 시작한다.
• 중괄호 { } 로 block을 구성한다.
• 주석은 # 이다.
• Caddyfile은 native JSON으로 adapter를 거쳐 변환된 뒤 로드된다.

example.com {
	root * /srv/www/example
	encode zstd gzip
	file_server
}

• 파일 맨 앞의 { … } 블록이다.
• admin API 주소, email, logging, storage, acme_ca 같은 전역 동작을 둔다.

{
	email [email protected]
	admin 127.0.0.1:2019
}

• example.com, :8080, https://example.com 같은 site address 다음에 block을 연다.
• 정적 파일 제공, reverse proxy, TLS 정책, header 조작 같은 HTTP handler를 둔다.

• root * /path: 문서 루트 지정
• file_server: 정적 파일 서빙
• reverse_proxy <upstream>: upstream으로 전달
• encode zstd gzip: 응답 압축
• header: 응답 헤더 추가/수정
• redir: redirect
• rewrite: 내부 경로 재작성
• handle / handle_path: 조건별 처리 분기
• tls: 인증서 경로 또는 issuer 동작 조정
• basic_auth: 기본 인증
• log: access log 설정

example.com {
	root * /srv/www/example
	encode zstd gzip
	file_server
}

app.example.com {
	reverse_proxy 127.0.0.1:3000
}

app.example.com {
	reverse_proxy 127.0.0.1:3000 {
		header_up Host {host}
		header_up X-Forwarded-Proto {scheme}
		header_up X-Forwarded-For {remote_host}
	}
}

:8080 {
	root * ./public
	file_server
}

• site address 또는 listen address
• root
• file_server

• site address 또는 listen address
• reverse_proxy

• public DNS가 맞는 site address
• 80/443 접근 가능 상태
• 필요 시 global email 또는 tls 세부 설정

• localhost 또는 .localhost 이름
• 필요 시 caddy trust 로 로컬 trust store 반영

• ./Caddyfile: 현재 작업 디렉터리의 기본 파일명
• /etc/caddy/Caddyfile: 배포판 패키지에서 흔한 경로
• native JSON은 별도 *.json 파일 또는 admin API payload로 운용할 수 있다.

• Caddyfile: 사람이 읽고 수정하기 편하다.
• native JSON: 구조가 명시적이고 API 자동화에 적합하다.
• caddy adapt –pretty 로 둘 사이를 비교해 보는 편이 좋다.

caddy fmt --overwrite ./Caddyfile
caddy adapt --config ./Caddyfile --pretty --validate
caddy validate --config ./Caddyfile
caddy reload --config ./Caddyfile

• fmt: Caddyfile 정렬
• adapt: JSON 변환과 adapter 수준 확인
• adapt –validate: provisioning 단계까지 포함한 강한 점검
• validate: 지정한 config가 실제 로드 가능한지 확인
• reload: 실행 중인 프로세스에 새 설정 반영

• 인증서 발급이 실패하면 DNS, 80/443 포트, 방화벽, upstream 이전 프록시 유무를 먼저 확인한다.
• JSON으로는 되는데 Caddyfile에서 실패하면 directive 문법보다 matcher 또는 block 범위를 먼저 확인한다.
• 로컬 경로를 못 읽으면 서비스 계정 권한과 parent directory traverse 권한을 본다.
• reverse_proxy 연결 오류는 upstream 포트, TLS 사용 여부, health check, header 조작을 확인한다.
• 자동 HTTPS를 원하지 않으면 site address의 scheme/port 지정과 TLS 관련 설정을 다시 검토한다.

• caddy
• config
• https
• openssl

• codex:: 2026-07-17 Added a Caddy configuration overview page with Caddyfile structure, common directives, and validation flow.