{{tag>[caddy webserver reverse-proxy]}}
====== Caddy ======
자동 HTTPS, 간결한 Caddyfile, 내장 reverse proxy 기능을 중심으로 많이 쓰는 웹 서버다.
===== Summary =====
* 단일 바이너리로 정적 파일 서버, reverse proxy, TLS 종료를 빠르게 구성할 수 있다.
* 사람이 직접 작성할 때는 보통 ''Caddyfile'' 을 쓰고, 자동화나 API 기반 배포에서는 native JSON 구성을 쓴다.
* 설정 반영 전에는 ''caddy adapt'' 와 ''caddy validate'' 로 확인하고, 실행 중 반영은 ''caddy reload'' 로 처리하는 편이 안전하다.
===== Installation =====
==== Debian / Ubuntu / Raspbian ====
공식 stable APT 저장소를 등록해 설치한다.
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy
* 패키지를 설치하면 ''caddy'' systemd service가 자동으로 시작된다.
* API 중심 구성용 ''caddy-api'' service unit도 포함되지만 기본으로 활성화되지는 않는다. 일반적인 Caddyfile 운용에서는 ''caddy'' service를 사용한다.
==== Fedora ====
공식 Caddy COPR 저장소를 활성화해 설치한다.
sudo dnf install dnf5-plugins
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy
==== RHEL / CentOS ====
공식 Caddy COPR 저장소를 활성화해 설치한다.
sudo dnf install dnf-plugins-core
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy
* Fedora와 RHEL/CentOS 패키지는 systemd service unit을 설치하지만 기본으로 활성화하지 않는다.
* Caddyfile 기반 service를 사용할 때는 설치 후 명시적으로 활성화하고 상태를 확인한다.
sudo systemctl enable --now caddy
systemctl status caddy
==== macOS ====
공식 설치 문서가 안내하는 community-maintained Homebrew formula를 사용한다.
brew install caddy
==== Windows ====
Caddy 공식 설치 문서는 community-maintained Chocolatey와 Scoop 패키지를 안내한다.
choco install caddy
또는:
scoop install caddy
2026-07-20 기준 Caddy 공식 설치 문서에는 ''winget'' 설치 방법이 안내되어 있지 않다. 출처가 불명확한 package ID를 임의로 사용하지 말고, 위의 문서화된 방법이나 공식 static binary를 사용한다. Windows service로 상시 실행하려면 설치와 별도로 공식 [[https://caddyserver.com/docs/running#windows-service|Windows service 안내]]를 따른다.
==== Verification ====
설치한 바이너리의 version과 build 정보를 확인한다. 배포 패키지나 custom build에 따라 포함된 module은 달라질 수 있다.
caddy version
caddy build-info
* 공식 설치 방법 및 최신 명령: [[https://caddyserver.com/docs/install|Caddy Install]]
* Linux/Windows service 운용: [[https://caddyserver.com/docs/running|Keep Caddy Running]]
===== Usage =====
* ''**caddy** [...] ARGS''
* ''**caddy** run --config FILE'': foreground 실행
* ''**caddy** start --config FILE'': background 실행
* ''**caddy** reload --config FILE'': 무중단 설정 재적용
* ''**caddy** adapt --config FILE'': Caddyfile 등을 JSON으로 변환
* ''**caddy** validate --config FILE'': 설정 유효성 점검
* ''**caddy** fmt --overwrite FILE'': Caddyfile 정렬
* ''**caddy** file-server [...]'': 빠른 정적 파일 서빙
* ''**caddy** reverse-proxy [...]'': 빠른 reverse proxy
===== Options =====
* ''run'': foreground에서 프로세스를 실행한다.
* ''start'': background로 프로세스를 시작한다.
* ''stop'': 실행 중인 Caddy 프로세스를 종료한다.
* ''reload'': admin API를 통해 현재 프로세스에 새 설정을 반영한다.
* ''adapt'': Caddyfile 같은 입력 구성을 native JSON으로 변환한다.
* ''validate'': 설정을 로드 가능한지 검증한다.
* ''fmt'': Caddyfile 포맷을 정렬한다.
* ''file-server'': 간단한 정적 파일 서버를 바로 띄운다.
* ''reverse-proxy'': 간단한 HTTP(S) reverse proxy를 바로 띄운다.
* ''trust'' / ''untrust'': 로컬 trust store에 인증서를 추가하거나 제거한다.
* ''list-modules'': 현재 빌드에 포함된 모듈을 확인한다.
===== Examples =====
* 현재 디렉터리를 정적 파일 서버로 빠르게 서빙
caddy file-server --root . --listen :8080
* 간단한 로컬 reverse proxy
caddy reverse-proxy --from :2080 --to :9000
* Caddyfile 포맷 정리
caddy fmt --overwrite ./Caddyfile
* Caddyfile을 JSON으로 변환하면서 검증
caddy adapt --config ./Caddyfile --pretty --validate
* 실행 중인 인스턴스에 설정 재반영
caddy reload --config ./Caddyfile
===== Config =====
* 기본 사람이 읽기 쉬운 형식은 ''Caddyfile'' 이다.
* native JSON은 admin API와 자동화 도구에서 다루기 좋다.
* 사이트 주소만 알 수 있으면 HTTPS를 자동으로 구성하려고 시도한다.
* 자세한 작성 규칙은 [[caddy:config]] 문서로 분리한다.
===== Troubleshooting =====
* ''caddy adapt'' 는 형식 변환 중심이고, 실제 로드 가능성까지 보려면 ''caddy validate'' 또는 ''caddy adapt --validate'' 가 더 강하다.
* public 도메인으로 HTTPS를 쓰면 DNS, 80/443 포트 개방, 외부 접근 가능 여부를 먼저 확인해야 한다.
* low port 바인딩이 실패하면 root 실행 여부보다 capability 또는 service manager 설정을 먼저 점검한다.
* ''reload'' 가 실패하면 admin API 주소, 실행 중인 프로세스, config adapter 지정 여부를 확인한다.
* 홈 디렉터리 아래 정적 파일이 보이지 않으면 systemd 서비스 계정의 디렉터리 traverse 권한 문제일 수 있다.
===== Compatibility =====
* 이 페이지는 로컬 바이너리 출력이 아니라 공식 Caddy 문서를 기준으로 2026-07-17에 정리했다.
* 실제 사용 가능한 subcommand와 모듈은 배포판 패키지, 빌드 옵션, 플러그인 포함 여부에 따라 달라질 수 있다.
* 자동 HTTPS 동작은 hostname, 공개 DNS, 포트 개방 상태, 내부 인증서 사용 여부에 따라 달라진다.
===== Help =====
+++ caddy help |
Local caddy help output was not captured in this repository checkout.
Use the official command line reference:
https://caddyserver.com/docs/command-line
+++
===== See Also =====
* [[caddy:config]]
* [[nginx]]
* [[nginx:config]]
* [[certbot:ko]]
* [[openssl:ko]]
===== History =====
* codex:: 2026-07-20 Added official Linux package installation, community-maintained macOS and Windows methods, service behavior, and version verification.
* codex:: 2026-07-17 Added a Caddy CLI reference page covering core subcommands, validation flow, and Caddyfile-oriented usage.
{{indexmenu>caddy:#1|js}}