Caddy

자동 HTTPS, 간결한 Caddyfile, 내장 reverse proxy 기능을 중심으로 많이 쓰는 웹 서버다.

• 단일 바이너리로 정적 파일 서버, reverse proxy, TLS 종료를 빠르게 구성할 수 있다.
• 사람이 직접 작성할 때는 보통 Caddyfile 을 쓰고, 자동화나 API 기반 배포에서는 native JSON 구성을 쓴다.
• 설정 반영 전에는 caddy adapt 와 caddy validate 로 확인하고, 실행 중 반영은 caddy reload 로 처리하는 편이 안전하다.

공식 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를 사용한다.

공식 Caddy COPR 저장소를 활성화해 설치한다.

sudo dnf install dnf5-plugins
sudo dnf copr enable @caddy/caddy
sudo dnf install caddy

공식 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

공식 설치 문서가 안내하는 community-maintained Homebrew formula를 사용한다.

brew install caddy

Caddy 공식 설치 문서는 community-maintained Chocolatey와 Scoop 패키지를 안내한다.

choco install caddy

또는:

scoop install caddy

설치한 바이너리의 version과 build 정보를 확인한다. 배포 패키지나 custom build에 따라 포함된 module은 달라질 수 있다.

caddy version
caddy build-info

• 공식 설치 방법 및 최신 명령: Caddy Install
• Linux/Windows service 운용: Keep Caddy Running

• caddy <command> [<switches>…] 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 [<switches>…]: 빠른 정적 파일 서빙
• caddy reverse-proxy [<switches>…]: 빠른 reverse proxy

• 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: 현재 빌드에 포함된 모듈을 확인한다.

• 현재 디렉터리를 정적 파일 서버로 빠르게 서빙

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

• 기본 사람이 읽기 쉬운 형식은 Caddyfile 이다.
• native JSON은 admin API와 자동화 도구에서 다루기 좋다.
• 사이트 주소만 알 수 있으면 HTTPS를 자동으로 구성하려고 시도한다.
• 자세한 작성 규칙은 config 문서로 분리한다.

• 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 권한 문제일 수 있다.

• 이 페이지는 로컬 바이너리 출력이 아니라 공식 Caddy 문서를 기준으로 2026-07-17에 정리했다.
• 실제 사용 가능한 subcommand와 모듈은 배포판 패키지, 빌드 옵션, 플러그인 포함 여부에 따라 달라질 수 있다.
• 자동 HTTPS 동작은 hostname, 공개 DNS, 포트 개방 상태, 내부 인증서 사용 여부에 따라 달라진다.

+ 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

+

• config
• nginx
• config
• certbot
• openssl

• 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.