Caddy

✒️ 2026-08-10 19:36 내용 수정

Go로 작성된 크로스 플랫폼 오픈 소스 웹 서버

• 위키백과 Caddy

• 공식 사이트 : https://caddyserver.com/

• HTTP 서버, TLS 자동화, PKI 앱 포함하는 표준 모듈 세트를 제공한다.

• 설정 방법이 Nginx에 비해 매우 간단하기에 관련 지식이 부족하다면 빠르게 사용하기에 유용하다.

구성 및 관리

• RESTful API를 통해 열린 소켓으로 수신되는 JSON으로 구성하거나, CLI를 사용하여 Caddyfile이라는 문서로 구성할 수 있다.
• 관리 소켓을 통해 구성(JSON, Caddyfile)이 수신되면 지정된 모든 모듈에 대한 구성을 디코딩한 후 모든 앱 모듈을 실행한다.

명령어

• 서버 제어 시 사용하는 주요 명령어를 정리했다.

설정 방법

파일 다운로드

• 운영 체제(Windows, macOS, Ubuntu 등)에 맞는 다운로드 방법들로 Caddy 파일을 다운로드한다.
  • Windows의 경우 공식 사이트의 download 페이지로 들어가면 Windows와 CPU 프로세서를 선택하고, 그에 맞는 Caddy 파일을 받을 수 있다.
  • macOS의 경우 Homebrew로 설치하는 방법들이 많이 추천되었다.
• 다운 받은 파일을 압축 해제한 뒤 caddy 실행 파일의 이름을 "caddy"로 수정한다.
  • caddy.exe 이름 확장자 형식으로 수정한다.

Caddyfile 구성

• caddy.exe 파일이 있는 디렉터리 경로에 Caddyfile 파일을 생성한다.
• 파일 내부에 로컬 호스트 요청 시 응답을 임의로 작성한 뒤에 테스트한다.
• 테스트를 위해 주소를 설정할 때 HTTP를 생략한다면 Caddy가 자동으로 HTTPS를 켜서 localhost용 내부 인증서로 TLS를 서비스한다.
  • localhost로만 테스트할 경우 HTTP를 명시하여 pki app module를 통한 로컬 인증서 생성을 진행하지 않고 서버를 실행할 수 있다.
  • TLS : 디지털 인증서를 제공하도록 요구하여 네트워크 상에서 안전하게 통신하기 위해 사용된 네트워크 보안 프로토콜

# 요청 주소
# localhost에서 TLS 없이 테스트할 때 HTTP 명시
http://localhost:8080

respond "Hello, world!"

• 리버스 프록시로 설정할 경우 reverse_proxy를 사용한다.
  • https://localhost:8080으로 요청을 전송하면 9000 포트에서 가동되는 서비스로 연결된다.

http://localhost:8080

reverse_proxy 127.0.0.1:9000

• Windows 환경 기준으로 cmd.exe(실행-cmd)에서 Caddyfile을 검증한다.
  • Caddyfile 내의 설정이 올바르게 작성되었는지 검증한다.
  • 여러 개의 Caddyfile을 사용할 경우 --confing 옵션을 사용하여 특정 Caddyfile을 지정할 수 있다.

# cmd
cd "caddy와 Caddyfile이 있는 경로"

./caddy.exe validate --config "Caddyfile이름"

Caddy 실행

• 검증이 완료되면 터미널에서 실행한다.
  • 터미널에서 로그를 확인하기 위해 run으로 실행했다.

./caddy.exe run --config "Caddyfile이름"

• 웹 브라우저로 https://localhost:8080을 입력하면 respond에 작성한 반환값 "Hello, world!"가 출력된다.

스크립트로 실행 관리하기

• 매번 cmd에서 caddy 명령어를 실행하는 것이 번거로워 claude code와 chatgpt로 실행 스크립트를 작성했다.

Caddy run

• chcp : cmd의 문자 인코딩(코드 페이지, Code Page)를 확인하거나 변경하는 명령어
  • 실행 스크립트 내에서 한글이나 특수문자 사용 시 글자가 깨지는 것을 막기 위해 코드 페이지를 변경할 때 사용 가능하다.
• >nul: Code Page 변경 시 Activate code page: 65001과 같은 결과 메시지를 화면에 표시하지 않을 때 사용한다.

# UTF-8 코드 페이지로 변환
chcp 65001

# 변경 완료 메시지 생략
chcp 65001 >nul

• run 스크립트의 동작은 다음과 같다.
  • 코드 페이지를 UTF-8로 변경하여 한글이나 특수문자 출력이 깨지지 않도록 설정한다.
  • 스크립트 이름을 Caddy - My Server로 지정한다.
  • 스크립트 실행을 위한 작업 디렉터리를 옮긴다.
  • Caddy 파일의 구성을 검증한다. 검증 실패 시 스크립트 실행을 중단한다.
  • 검증 성공 시 Caddy 서버를 포그라운드로 실행한다.
• 절대 경로가 아닌 스크립트 자기의 위치 %~dp0를 사용한다.
  • cd /d "%~dp0"는 Caddyfile 탐색과 접근 기록 파일 등을 생성할 위치를 맞추기 위해 추가한 것으로, 경로가 바뀐다면 각각의 파일에 맞는 경로를 따로 지정해야 한다.

@echo off
chcp 65001 >nul
title Caddy run - My Server
cd /d "%~dp0"

"%~dp0caddy.exe" validate --config Caddyfile --adapter caddyfile
if errorlevel 1 (
	echo.
	echo [실패] Caddyfile 문법 오류입니다. 가동하지 않았습니다.
	pause
	exit /b 1
)

echo.
echo [기동] http://localhost:8080/ ^(종료: Ctrl+C^)
echo.
"%~dp0caddy.exe" run --config Caddyfile --adapter caddyfile

Caddy reload

• Caddyfile을 변경한 후 서버 재시작 없이 구성 파일을 변경할 때 사용하는 스크립트다.
• timeout /t n : n초 동안 대기한다.
• timeout /nobreak : 사용자의 입력으로 대기가 중단되지 않는다.
• >nul 2>nul : 명령어의 표준 출력과 표준 에러를 표시하지 않는다.

@echo off
chcp 65001 >nul
title Caddy reload - My Server
cd /d "%~dp0"

"%~dp0caddy.exe" reload --config Caddyfile --adapter caddyfile
if errorlevel 1 (
	echo.
	echo [실패] 반영 실패. 문법 오류거나 Caddy가 실행 중이 아닙니다.
	pause
	exit /b 1
)

echo.
echo [완료] Caddyfile 반영됨
""%SystemRoot\System32\timeout.exe" /t 2 /nobreak >nul 2>nul

Caddy stop

• 백그라운드에서 실행 중인 Caddy 서버를 중단시킬 때 사용하는 스크립트다.
• 중단 실패 시 Caddy가 작동 중인지 확인하기 위해 Caddy가 사용 중인 포트가 열려있는지 확인하는 netstat 명령어를 터미널에 보여준다.
  • netstat -ano : 컴퓨터 네트워크 연결과 Listening중인 포트를 표시
    • -a : 활성 연결을 표시
    • -n : 주소와 포트를 숫자로 표시
    • -o : 연결에 해당하는 프로세스 ID를 표시
  • | findstr <text> : 출력 결과에서 text와 일치하는 문자열이나 패턴을 검색

@echo off
chcp 65001 >nul
title Caddy stop - My Server
cd /d "%~dp0"

"%~dp0caddy.exe" stop
if errorlevel 1 (
	echo.
	echo [실패] 종료 실패. 실행 중이 아니거나 admin API에 접근할 수 없습니다.
	echo netstat -ano ^| findstr :8080
	pause
	exit /b 1
)

echo.
echo [완료] Caddy 종료됨
""%SystemRoot\System32\timeout.exe" /t 2 /nobreak >nul 2>nul