Caddyfile 튜토리얼

원문 보기 위키 갱신 2026.10.03

Caddyfile 튜토리얼 (Caddyfile Tutorial)

이 튜토리얼은 HTTP Caddyfile의 기본을 가르쳐서, 멋지고 기능적인 사이트 설정을 빠르고 쉽게 만들 수 있도록 도와줘요.

출처: Caddy 공식 문서

본문

이 튜토리얼은 HTTP Caddyfile의 기본을 가르쳐서, 멋지고 기능적인 사이트 설정을 빠르고 쉽게 만들 수 있도록 도와줘요.

목표(Objectives):

🔲 첫 번째 사이트 (First site)
🔲 정적 파일 서버 (Static file server)
🔲 템플릿 (Templates)
🔲 압축 (Compression)
🔲 여러 사이트 (Multiple sites)
🔲 Matchers
🔲 환경 변수 (Environment variables)
🔲 주석 (Comments)

사전 요구 사항(Prerequisites):

기본 터미널 / 명령줄 기술
기본 텍스트 편집기 기술
PATH 안의 caddy

Caddyfile이라는 새 텍스트 파일(확장자 없이)을 만들어요.

먼저 입력해야 할 것은 사이트의 주소예요:

localhost

HTTP와 HTTPS 포트(각각 80과 443)가 OS에서 특권 포트라면, 상승된 권한으로 실행하거나 더 높은 포트를 사용해야 해요. 더 높은 포트를 쓰려면 주소를 localhost:2015처럼 바꾸고 http_port Caddyfile 옵션으로 HTTP 포트를 바꾸면 돼요.

그런 다음 엔터를 누르고 원하는 동작을 입력해요. 이 튜토리얼에서는 Caddyfile이 이렇게 보이게 해요:

localhost

respond "Hello, world!"

저장하고 Caddy를 실행해요(훈련용 튜토리얼이므로 --watch 플래그를 써서 Caddyfile 변경이 자동으로 적용되게 할게요):

caddy run --watch

권한 에러가 나면 주소에 더 높은 포트(예: localhost:2015)를 사용하고 HTTP 포트를 바꾸거나, 상승된 권한으로 실행해요.

처음에는 비밀번호를 물어볼 거예요. Caddy가 사이트를 HTTPS로 서빙할 수 있게 하기 위해서예요.

Caddy는 사이트 주소의 일부로 호스트나 IP가 있는 한 모든 사이트를 기본적으로 HTTPS로 서빙해요. 주소 앞에 http://를 명시적으로 붙이면 자동 HTTPS를 비활성화할 수 있어요.

첫 번째 사이트 (First site)

브라우저에서 localhost를 열어 웹 서버가 HTTPS까지 완비되어 동작하는 걸 확인해요.

처음에는 인증서 에러가 나면 브라우저를 다시 시작해야 할 수 있어요.

그건 특별히 흥미롭지 않으니, 정적 응답을 디렉터리 목록이 활성화된 파일 서버로 바꿔볼게요:

localhost

file_server browse

Caddyfile을 저장한 다음 브라우저 탭을 새로고침해요. 현재 디렉터리에 인덱스 파일이 있으면 파일 목록이나 HTML 페이지를 볼 수 있을 거예요.

정적 파일 서버 (Static file server)

기능 추가하기 (Adding functionality)

파일 서버로 흥미로운 걸 해봐요. 템플릿 페이지를 서빙할 거예요. 새 파일을 만들고 이것을 붙여넣어요:

<!DOCTYPE html>
<html>
	<head>
		<title>Caddy tutorial</title>
	</head>
	<body>
		Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}
	</body>
</html>

이것을 현재 디렉터리에 caddy.html로 저장하고 브라우저에서 로드해요: https://localhost/caddy.html

출력은:

Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}

잠깐만요. 오늘 날짜가 보여야 하는데 왜 안 될까요? 서버가 아직 템플릿을 평가하도록 설정되지 않았기 때문이에요! 고치기 쉬워요. Caddyfile에 한 줄을 추가해서 이렇게 보이게 해요:

localhost

templates
file_server browse

저장한 다음 브라우저 탭을 새로고침해요. 이렇게 보일 거예요:

Page loaded at: Fri Oct 2 16:36:12 UTC 2026

Caddy의 templates 모듈로 정적 파일에 대해 많은 유용한 작업을 할 수 있어요. 다른 HTML 파일 포함, 하위 요청 만들기, 응답 헤더 설정, 데이터 구조 다루기 등등!

템플릿 (Templates)

빠르고 현대적인 압축 알고리즘으로 응답을 압축하는 게 좋은 습관이에요. encode 지시문으로 Gzip과 Zstandard 지원을 활성화해볼게요:

localhost

encode
templates
file_server browse

압축 (Compression)

이게 반-고급 수준의 프로덕션 준비 사이트를 띄우는 기본 과정이에요!

자동 HTTPS를 켤 준비가 되면 사이트 주소(튜토리얼의 localhost)를 도메인 이름으로 바꾸면 돼요. 자세한 내용은 HTTPS 빠른 시작 가이드를 참고해요.

여러 사이트 (Multiple sites)

현재 Caddyfile로는 사이트 정의를 하나만 가질 수 있어요! 첫 번째 줄만 사이트의 주소가 될 수 있고, 파일의 나머지는 전부 그 사이트를 위한 지시문이어야 해요.

하지만 더 많은 사이트를 추가할 수 있게 만드는 건 쉬워요!

지금까지의 Caddyfile:

localhost

encode
templates
file_server browse

은 이것과 동일해요:

localhost {
	encode
	templates
	file_server browse
}

단 두 번째 것은 더 많은 사이트를 추가할 수 있게 해줘요.

사이트 블록을 중괄호 { }로 감싸면 같은 Caddyfile에서 여러 다른 사이트를 정의할 수 있어요.

예를 들어:

:8080 {
	respond "I am 8080"
}

:8081 {
	respond "I am 8081"
}

사이트 블록을 중괄호로 감쌀 때, 중괄호 밖에는 주소만, 안에는 지시문만 나타나요.

같은 설정을 공유하는 여러 사이트에는 주소를 더 추가할 수 있어요. 예를 들어:

:8080, :8081 {
	...
}

그럼 각 주소가 고유하기만 하면 원하는 만큼 많은 다른 사이트를 정의할 수 있어요.

여러 사이트 (Multiple sites)

Matchers

일부 지시문을 특정 요청에만 적용하고 싶을 수 있어요. 예를 들어 파일 서버와 리버스 프록시를 둘 다 원한다고 가정해봐요. 하지만 분명히 모든 요청에 둘 다 할 수는 없어요! 파일 서버가 정적 파일로 응답을 쓰거나, 리버스 프록시가 요청을 백엔드로 전달하고 그 응답을 쓸 거예요.

이 설정은 우리가 원하는 대로 동작하지 않아요(reverse_proxy가 지시문 순서 때문에 우선할 거예요):

localhost

file_server
reverse_proxy 127.0.0.1:9005

실제로는 API 요청, 즉 기본 경로가 /api/인 요청에만 리버스 프록시를 쓰고 싶을 거예요. matcher 토큰을 추가하면 쉽게 됩니다:

localhost

reverse_proxy /api/* 127.0.0.1:9005
file_server

됐어요. 이제 /api/로 시작하는 모든 요청에 리버스 프록시가 우선할 거예요.

방금 추가한 /api/* 부분을 matcher 토큰이라고 불러요. 슬래시 /로 시작하고 지시문 바로 뒤에 나타나므로 matcher 토큰임을 알 수 있어요(지만 확실히 하려면 지시문 문서에서 찾아볼 수 있어요).

Matcher는 정말 강력해요. 이름 있는 matcher를 선언하고 @name처럼 사용해 요청 경로보다 더 많은 것에 매칭할 수 있어요! 계속하기 전에 잠시 matcher에 대해 더 알아보세요!

Matchers

환경 변수 (Environment variables)

Caddyfile 어댑터는 Caddyfile이 파싱되기 전에 환경 변수를 치환할 수 있게 해줘요.

먼저 환경 변수를 설정해요(Caddy를 실행하는 같은 셸에서):

export SITE_ADDRESS=localhost:9055

그런 다음 Caddyfile에서 이렇게 사용할 수 있어요:

{$SITE_ADDRESS}

file_server

Caddyfile이 파싱되기 전에 이렇게 확장될 거예요:

localhost:9055

file_server

Caddyfile 어디에서든, 원하는 수의 토큰에 환경 변수를 사용할 수 있어요.

환경 변수 (Environment variables)

주석 (Comments)

마지막으로 매우 유용하게 쓸 한 가지. Caddyfile에서 무엇을 메모하거나 주석을 달고 싶다면 #로 시작하는 주석을 사용할 수 있어요:

# this starts a comment

주석 (Comments)

추가 읽을거리 (Further reading)

더 알아보기 (Learn more)

Caddy 공식 문서