시작하기

원문 보기 위키 갱신 2026.10.03

시작하기 (Getting Started)

출처: Caddy 공식 문서

본문

Caddy에 오신 것을 환영해요! 이 튜토리얼은 Caddy 사용의 기본을 살펴보고 높은 수준에서 Caddy에 익숙해지도록 도와줘요.

목표:

🔲 데몬 실행하기
🔲 API 사용해 보기
🔲 Caddy에 설정 주기
🔲 설정 테스트하기
🔲 Caddyfile 만들기
🔲 설정 어댑터 사용하기
🔲 초기 설정으로 시작하기
🔲 JSON과 Caddyfile 비교하기
🔲 API와 설정 파일 비교하기
🔲 백그라운드로 실행하기
🔲 무중단 설정 리로드

사전 준비:

기본적인 터미널/명령줄 사용 능력
기본적인 텍스트 편집기 사용 능력
PATH에 caddy와 curl이 있어야 해요

패키지 관리자로 Caddy를 설치했다면 Caddy가 이미 서비스로 실행 중일 수 있어요. 그렇다면 이 튜토리얼을 시작하기 전에 서비스를 중지해 주세요.

먼저 실행해 봐요:

caddy

이런; 서브커맨드 없이는 caddy 명령은 도움말 텍스트만 보여줘요. 무엇을 해야 할지 잊었을 때 언제든 이걸 사용할 수 있어요.

Caddy를 데몬으로 시작하려면 run 서브커맨드를 사용해요:

caddy run

데몬 실행하기 이것은 영원히 블록되지만, 무엇을 하는 걸까요? 지금은... 아무것도 하지 않아요. 기본적으로 Caddy의 설정("config")은 비어 있어요. 다른 터미널에서 admin API로 이를 확인할 수 있어요:

curl localhost:2019/config/

이것은 여러분의 웹사이트가 아니에요: localhost:2019의 관리 엔드포인트는 Caddy를 제어하는 데 사용되며 기본적으로 localhost로 제한돼요.

API 사용해 보기 Caddy에 설정을 주면 Caddy를 유용하게 만들 수 있어요. 이 작업은 여러 방법으로 할 수 있지만, 다음 섹션에서 curl로 /load 엔드포인트에 POST 요청을 하는 것으로 시작할 거예요.

첫 번째 설정

요청을 준비하려면 설정을 만들어야 해요. 핵심적으로 Caddy의 설정은 단순한 JSON 문서예요.

이 내용을 JSON 파일(예: caddy.json)로 저장해요:

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

설정 파일을 꼭 써야 하는 건 아니지만, 이 튜토리얼에서는 설정 파일을 사용할 거예요. Caddy의 admin API는 다른 프로그램이나 스크립트가 사용하도록 설계되었어요.

그다음 업로드해요:

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

Caddy에 설정 주기 또 다른 GET 요청으로 Caddy가 우리의 새 설정을 적용했는지 확인할 수 있어요:

curl localhost:2019/config/

브라우저에서 localhost:2015로 이동하거나 curl을 사용해서 동작하는지 확인해요:

curl localhost:2015
Hello, world!

*Hello, world!*가 보인다면 축하해요 — 동작하는 거예요! 설정이 여러분이 기대한 대로 동작하는지 확인하는 것은 항상 좋은 습관이에요. 특히 프로덕션에 배포하기 전에는요.

설정 테스트하기

첫 번째 Caddyfile

Hello World 하나 때문에 꽤 많은 작업을 했네요.

Caddy를 설정하는 또 다른 방법은 **Caddyfile**을 쓰는 거예요. 위에서 JSON으로 작성한 것과 같은 설정을 이렇게 간단히 표현할 수 있어요:

:2015

respond "Hello, world!"

이것을 현재 디렉터리에 Caddyfile(확장자 없음)이라는 파일로 저장해요.

Caddyfile 만들기 Caddy가 이미 실행 중이라면 중지하고(Ctrl+C), 이렇게 실행해요:

caddy adapt

Caddyfile을 다른 곳에 저장했거나 Caddyfile이 아닌 다른 이름으로 저장했다면:

caddy adapt --config /path/to/Caddyfile

JSON 출력이 보일 거예요! 여기서 무슨 일이 일어난 걸까요?

방금 **설정 어댑터**를 사용해 Caddyfile을 Caddy의 네이티브 JSON 구조로 변환했어요.

설정 어댑터 사용하기 그 출력을 가져와 또 다른 API 요청을 할 수도 있지만, caddy 명령이 우리 대신 해주기 때문에 그 모든 단계를 건너뛸 수 있어요. 현재 디렉터리에 Caddyfile이라는 파일이 있고 다른 설정이 지정되지 않았다면, Caddy가 Caddyfile을 로드해 우리를 위해 어댑트하고 바로 실행해요.

이제 현재 폴더에 Caddyfile이 있으니 다시 caddy run을 실행해 봐요:

caddy run

또는 Caddyfile이 다른 곳에 있다면:

caddy run --config /path/to/Caddyfile

(다른 이름으로 되어 있고 "Caddyfile"로 시작하지 않는다면 --adapter caddyfile을 지정해야 해요.)

이제 사이트를 다시 로드해 보면 동작하는 걸 볼 수 있어요!

초기 설정으로 시작하기 보시다시피, Caddy를 초기 설정으로 시작하는 방법은 여러 가지가 있어요:

현재 디렉터리의 Caddyfile이라는 파일
--config 플래그(선택적으로 --adapter 플래그와 함께)
--resume 플래그(이전에 설정이 로드된 적이 있다면)

JSON vs. Caddyfile

이제 Caddyfile이 여러분을 위해 JSON으로 변환된다는 것을 알았어요.

Caddyfile이 JSON보다 쉬워 보이지만, 항상 Caddyfile을 써야 할까요? 각 접근 방식에는 장단점이 있어요. 답은 여러분의 요구 사항과 사용 사례에 달려 있어요.

JSON	Caddyfile
생성하기 쉬움	손으로 만들기 쉬움
프로그래밍하기 쉬움	자동화하기 어색함
매우 표현력이 풍부함	적당히 표현력이 있음
Caddy 기능의 전체 범위	Caddy 기능의 대부분
설정 순회 가능	Caddyfile 내에서 순회 불가
부분 설정 변경 가능	전체 설정 변경만 가능
내보낼 수 있음	내보낼 수 없음
모든 API 엔드포인트와 호환	일부 API 엔드포인트와 호환
문서 자동 생성	문서는 손으로 작성
보편적	틈새
더 효율적	더 계산 비용이 높음
좀 지루함	좀 재미있음
더 알아보기: JSON 구조	더 알아보기: Caddyfile 문서

어떤 것이 여러분의 사용 사례에 가장 좋은지 결정해야 해요.

JSON과 Caddyfile(그리고 그 외 지원되는 모든 설정 어댑터) 모두 Caddy의 API와 함께 사용할 수 있다는 점을 기억하는 게 중요해요. 하지만 JSON을 사용하면 Caddy 기능과 API 기능의 전체 범위를 얻을 수 있어요. 설정 어댑터를 사용한다면 API로 설정을 로드하거나 변경하는 유일한 방법은 /load 엔드포인트예요.

JSON과 Caddyfile 비교하기

API vs. 설정 파일

내부적으로는 설정 파일도 Caddy의 API 엔드포인트를 거쳐요. caddy 명령이 그 API 호출들을 여러분을 위해 포장해 줄 뿐이에요.

또한 워크플로를 API 기반으로 할지 CLI 기반으로 할지도 결정해야 해요. (같은 서버에서 API와 설정 파일을 둘 다 사용할 수는 있지만 권장하지 않아요: 진실의 원천(source of truth)은 하나가 좋아요.)

API	설정 파일
HTTP 요청으로 설정 변경	셸 명령으로 설정 변경
확장하기 쉬움	확장하기 어려움
손으로 관리하기 어려움	손으로 관리하기 쉬움
정말 재미있음	이것도 재미있음
더 알아보기: API 튜토리얼	더 알아보기: Caddyfile 튜토리얼

적절한 도구(예: 어떤 REST 클라이언트 앱이든)를 사용하면 API로 서버 설정을 수동으로 관리하는 것도 충분히 가능해요.

API 또는 설정 파일 워크플로의 선택은 설정 어댑터 사용과는 독립적이에요: JSON을 사용하되 파일에 저장하고 명령줄 인터페이스를 쓸 수도 있고, 반대로 Caddyfile을 API와 함께 쓸 수도 있어요.

하지만 대부분의 사람들은 JSON+API 또는 Caddyfile+CLI 조합을 사용할 거예요.

보시다시피 Caddy는 다양한 사용 사례와 배포 환경에 잘 맞아요!

API와 설정 파일 비교하기

시작, 중지, 실행

Caddy는 서버이므로 무기한 실행돼요. 즉, 프로세스가 종료될 때까지(보통 Ctrl+C) caddy run을 실행한 후에도 터미널이 풀리지 않아요.

caddy run이 가장 흔하고 보통 권장되지만(특히 시스템 서비스를 만들 때!), 대신 caddy start로 Caddy를 시작해 백그라운드에서 실행하게 할 수도 있어요:

caddy start

이러면 터미널을 다시 사용할 수 있어서, 대화형 헤드리스 환경에서 편리해요.

그런 다음에는 프로세스를 직접 중지해야 해요. Ctrl+C로는 중지되지 않으니까요:

caddy stop

또는 API의 /stop 엔드포인트를 사용해요.

백그라운드로 실행하기

설정 리로드

여러분의 서버는 무중단 설정 리로드/변경을 수행할 수 있어요.

설정을 로드하거나 변경하는 모든 API 엔드포인트는 무중단으로 우아하게(gracefully) 동작해요.

하지만 명령줄을 사용할 때는 Ctrl+C로 서버를 중지한 다음 새 설정을 적용하려고 다시 시작하고 싶은 유혹이 들 수 있어요. 그러지 마세요: 서버를 중지하고 시작하는 것은 설정 변경과는 별개의 일이며, 다운타임이 발생해요.

서버를 중지하면 서버가 죽게 됩니다.

대신 caddy reload 명령으로 우아한 설정 변경을 해요:

caddy reload

이것은 실제로 내부적으로 API를 사용해요. 설정 파일을 로드하고, 필요하면 JSON으로 어댑트한 다음, 무중단으로 활성 설정을 우아하게 교체해요.

새 설정을 로드하는 중에 오류가 있으면 Caddy는 마지막으로 동작하던 설정으로 롤백해요.

기술적으로 새 설정이 시작된 후에야 이전 설정이 중지되므로, 잠시 동안 두 설정이 모두 실행되고 있어요! 새 설정이 실패하면 오류와 함께 중단되고, 이전 설정은 그냥 중지되지 않아요.

무중단 설정 리로드

더 알아보기 (Learn more)

Caddy 공식 문서