Caddy 계속 실행하기

원문 보기 위키 갱신 2026.10.03

Caddy 계속 실행하기 (Keep Caddy Running)

출처: Caddy 공식 문서

본문

Caddy는 명령줄 인터페이스로 직접 실행할 수 있지만, 시스템 재부팅 시 자동으로 시작되게 하고 stdout/stderr 로그를 포착하기 위해 서비스 관리자를 사용해 계속 실행하는 데는 수많은 이점이 있어요.

Linux 서비스
유닛 파일
수동 설치
서비스 사용
로컬 HTTPS
오버라이드
환경 변수
run 및 reload 오버라이드
크래시 시 재시작
SELinux 고려 사항
Windows 서비스
sc.exe
WinSW
Docker Compose
설정
사용
로컬 HTTPS

Linux 서비스

systemd가 있는 Linux 배포판에서 Caddy를 실행하는 권장 방법은 공식 systemd 유닛 파일을 사용하는 거예요.

유닛 파일

사용 사례에 따라 선택할 수 있는 두 가지 systemd 유닛 파일을 제공해요:

caddy.service — Caddyfile로 Caddy를 구성하는 경우예요. 다른 설정 어댑터나 JSON 설정 파일을 사용하고 싶다면 ExecStart와 ExecReload 명령을 오버라이드할 수 있어요.
caddy-api.service — Caddy를 API로만 구성하는 경우예요. 이 서비스는 기본으로 영속화되는 autosave.json으로 Caddy를 시작하는 --resume 옵션을 사용해요.

이 둘은 매우 비슷하지만, 워크플로를 수용하기 위해 ExecStart와 ExecReload 명령이 달라요.

서비스 간에 전환해야 한다면, 다른 하나를 활성화·시작하기 전에 이전 것을 비활성화하고 중지해야 해요. 예를 들어 caddy 서비스에서 caddy-api 서비스로 전환하려면:

sudo systemctl disable --now caddy
sudo systemctl enable --now caddy-api

수동 설치

일부 설치 방법은 Caddy가 서비스로 실행되도록 자동으로 설정해요. 그렇게 하지 않은 방법을 선택했다면 다음 지침을 따라 직접 설정할 수 있어요:

요구 사항:

다운로드하거나 소스에서 빌드한 caddy 바이너리
systemctl --version 232 이상
sudo 권한

caddy 바이너리를 $PATH로 옮겨요. 예를 들어:

sudo mv caddy /usr/bin/

동작하는지 확인해요:

caddy version

caddy라는 그룹을 만들어요:

sudo groupadd --system caddy

쓰기 가능한 홈 디렉터리를 가진 caddy라는 사용자를 만들어요:

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

설정 파일을 사용한다면 방금 만든 caddy 사용자가 읽을 수 있는지 확인하세요.

다음으로, 사용 사례에 따라 systemd 유닛 파일을 선택해요.

ExecStart와 ExecReload 지시문을 다시 확인하세요. 바이너리의 위치와 명령줄 인자가 여러분의 설치에 맞는지 확인해요! 예를 들어 설정 파일을 사용한다면 기본값과 다를 때 --config 경로를 바꿔 주세요.

서비스 파일을 저장하는 일반적인 위치는 /etc/systemd/system/caddy.service예요.

서비스 파일을 저장한 후, 일반적인 systemctl 절차로 서비스를 처음 시작할 수 있어요:

sudo systemctl daemon-reload
sudo systemctl enable --now caddy

실행 중인지 확인해요:

systemctl status caddy

이제 서비스 사용할 준비가 됐어요!

서비스 사용

Caddyfile을 사용한다면 nano, vi, 또는 선호하는 편집기로 설정을 편집할 수 있어요:

sudo nano /etc/caddy/Caddyfile

정적 사이트 파일은 /var/www/html 또는 /srv에 둘 수 있어요. caddy 사용자가 파일을 읽을 권한이 있는지 확인하세요.

서비스가 실행 중인지 확인하려면:

systemctl status caddy

status 명령은 현재 실행 중인 서비스 파일의 위치도 보여줘요.

공식 서비스 파일로 실행할 때 Caddy의 출력은 journalctl로 리다이렉트돼요. 전체 로그를 읽고 줄이 잘리지 않게 하려면:

journalctl -u caddy --no-pager | less +G

설정 파일을 사용한다면 변경 후 Caddy를 우아하게 리로드할 수 있어요:

sudo systemctl reload caddy

서비스를 중지하려면:

sudo systemctl stop caddy

Caddy의 설정을 바꾸려고 서비스를 중지하지 마세요. 서버를 중지하면 다운타임이 발생해요. 대신 reload 명령을 사용하세요.

Caddy 프로세스는 $HOME이 /var/lib/caddy로 설정된 caddy 사용자로 실행돼요. 즉:

기본 데이터 저장 위치(인증서 및 기타 상태 정보용)는 /var/lib/caddy/.local/share/caddy에 있어요.
기본 설정 저장 위치(자동 저장된 JSON 설정용, 주로 caddy-api 서비스에 유용)는 /var/lib/caddy/.config/caddy에 있어요.

systemd로 로컬 HTTPS

개발용 HTTPS로 Caddy를 사용할 때 localhost나 app.localhost 같은 호스트 이름을 사용할 수 있어요. 이러면 Caddy의 로컬 CA로 인증서를 발급하는 로컬 HTTPS가 활성화돼요.

Caddy는 서비스로 실행될 때 caddy 사용자로 실행되므로, 시스템 신뢰 저장소에 루트 CA 인증서를 설치할 권한이 없어요. 설치하려면 sudo caddy trust를 실행해 설치를 수행하세요.

internal발급자를 사용할 때 다른 기기에서 서버에 연결하려면 그 기기에도 루트 CA 인증서를 설치해야 해요. 루트 CA 인증서는 /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt에서 찾을 수 있어요. 많은 웹 브라우저가 이제 자체 신뢰 저장소를 사용하므로(시스템의 신뢰 저장소 무시), 거기에도 인증서를 수동으로 설치해야 할 수 있어요.

오버라이드

서비스 파일의 측면을 오버라이드하는 가장 좋은 방법은 이 명령이에요:

sudo systemctl edit caddy

이러면 기본 터미널 텍스트 편집기로 빈 파일이 열리고, 유닛 정의에 지시문을 오버라이드하거나 추가할 수 있어요. 이를 "drop-in" 파일이라고 해요.

환경 변수

설정에서 사용할 환경 변수를 정의해야 한다면 이렇게 할 수 있어요:

[Service]
Environment="CF_API_TOKEN=super-secret-cloudflare-tokenvalue"

비슷하게, 환경 변수를 별도의 파일(envfile)로 유지하는 것을 선호한다면 EnvironmentFile 지시문을 이렇게 사용할 수 있어요:

[Service]
EnvironmentFile=/etc/caddy/.env

그러면 /etc/caddy/.env 파일은 이렇게 보일 수 있어요(값 주위에 " 따옴표를 사용하지 마세요):

CF_API_TOKEN=super-secret-cloudflare-tokenvalue

`run` 및 `reload` 오버라이드

기본값인 Caddyfile 대신 설정 파일을 JSON 파일로 바꿔야 한다면(참고: Exec* 지시문은 새 값을 설정하기 전에 빈 문자열로 리셋해야 해요):

[Service]
ExecStart=
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/caddy.json
ExecReload=
ExecReload=/usr/bin/caddy reload --config /etc/caddy/caddy.json

크래시 시 재시작

caddy가 예기치 않게 크래시하면 5초 후에 자동으로 재시작되게 하려면:

[Service]
# Automatically restart caddy if it crashes except if the exit code was 1
RestartPreventExitStatus=1
Restart=on-failure
RestartSec=5s

그다음 파일을 저장하고 텍스트 편집기를 나간 뒤, 효과가 적용되도록 서비스를 재시작해요:

sudo systemctl restart caddy

SELinux 고려 사항

SELinux가 활성화된 시스템에는 두 가지 옵션이 있어요:

COPR 저장소로 Caddy를 설치해요. 그러면 systemd 파일과 caddy 바이너리가 이미 올바르게 생성·레이블링돼 있어요(그래서 이 섹션은 무시해도 됩니다). 커스텀 Caddy 빌드를 사용하려면 아래 설명대로 실행 파일에 레이블을 지정해야 해요.
이 사이트에서 Caddy를 다운로드하거나 xcaddy로 컴파일해요. 어느 경우든 파일에 직접 레이블을 지정해야 해요.

systemd 유닛 파일과 그 실행 파일은 각각 systemd_unit_file_t와 bin_t로 레이블링되지 않으면 실행되지 않아요.

systemd_unit_file_t 레이블은 /etc/systemd/...에 생성된 파일에 자동으로 적용되므로, 수동 설치 지침대로 caddy.service 파일을 거기에 만드세요.

caddy 바이너리에 태그하려면 다음 명령을 사용할 수 있어요:

semanage fcontext -a -t bin_t /usr/bin/caddy && restorecon -Rv /usr/bin/caddy

Windows 서비스

Windows에서 Caddy를 서비스로 실행하는 방법은 두 가지가 있어요: sc.exe 또는 WinSW.

sc.exe

서비스를 만들려면 실행해요:

sc.exe create caddy start= auto binPath= "YOURPATH\caddy.exe run"

(YOURPATH를 caddy.exe의 실제 경로로 바꾸세요)

시작하려면:

sc.exe start caddy

중지하려면:

sc.exe stop caddy

WinSW

이 지침으로 Windows에 Caddy를 서비스로 설치해요.

요구 사항:

다운로드하거나 소스에서 빌드한 caddy.exe 바이너리
WinSW 서비스 래퍼 최신 릴리스의 .exe (아래 서비스 설정은 v2.x 릴리스용으로 작성됨)

모든 파일을 서비스 디렉터리에 넣어요. 다음 예시에서는 C:\caddy를 사용해요.

WinSW-x64.exe 파일을 caddy-service.exe로 이름을 바꿔요.

같은 디렉터리에 caddy-service.xml을 추가해요:

<service>
  <id>caddy</id>
  <!-- Display name of the service -->
  <name>Caddy Web Server (powered by WinSW)</name>
  <!-- Service description -->
  <description>Caddy Web Server (https://caddyserver.com/)</description>
  <executable>%BASE%\caddy.exe</executable>
  <arguments>run</arguments>
  <log mode="roll-by-time">
    <pattern>yyyy-MM-dd</pattern>
  </log>
</service>

이제 서비스를 설치할 수 있어요:

caddy-service install

Windows 서비스 콘솔을 열어 서비스가 올바르게 실행 중인지 확인하고 싶을 수 있어요:

services.msc

Windows 서비스는 리로드할 수 없으므로, caddy에 직접 리로드하라고 해야 한다는 점을 유의하세요:

caddy reload

재시작은 작업 관리자의 "서비스" 탭을 통한 일반적인 Windows 서비스 명령으로 가능해요.

서비스 래퍼를 커스터마이즈하려면 WinSW 문서를 참조하세요.

Docker Compose

Docker로 시작하는 가장 간단한 방법은 Docker Compose를 사용하는 거예요. 공식 Caddy Docker 이미지에 대한 추가 세부 사항은 Docker Hub의 문서를 참조하세요.

이것은 명령이 이제 docker compose(공백)인 Docker Compose V2를 사용한다고 가정해요. V1의 docker-compose(하이픈)가 아니라요.

설정

먼저 compose.yml 파일을 만들어요(또는 기존 파일에 이 서비스를 추가해요):

services:
  caddy:
    image: caddy:<version>
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy
      - ./site:/srv
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Docker Hub의 "Tags" 섹션에 나열된 최신 버전 번호로 이미지 <version>을 꼭 채워 주세요.

이것이 하는 일:

unless-stopped 재시작 정책을 사용해 머신이 재부팅될 때 Caddy 컨테이너가 자동으로 재시작되게 해요.
HTTP용 80, HTTPS용 443, 그리고 HTTP/3용 443/udp에 바인딩해요.
Caddyfile 설정을 담은 conf 디렉터리를 바인드 마운트해요.
/srv에서 사이트의 정적 파일을 서빙하기 위해 site 디렉터리를 바인드 마운트해요.
/data와 /config를 위한 명명된 볼륨으로 중요한 정보를 영속화해요.

그다음 conf 디렉터리에서 유일한 파일로 Caddyfile이라는 파일을 만들고 Caddyfile 설정을 작성해요.

서빙할 정적 파일이 있다면 설정 옆의 site/ 디렉터리에 놓고 root를 root /srv로 설정하면 돼요. 없다면 /srv 볼륨 마운트를 제거해도 돼요.

Caddy로 다른 컨테이너에 리버스 프록시를 한다면, Docker 네트워킹에서 localhost는 "이 머신"이 아니라 "이 컨테이너"를 의미한다는 점을 기억하세요. 그래서 예를 들어 reverse_proxy localhost:8080을 쓰지 말고 reverse_proxy other-container:8080을 사용하세요.

앱이 리슨하는 포트를 사용하되, 호스트에 게시된 포트가 아니라 컨테이너 내부에서 리슨하는 포트를 사용하세요. 예를 들어 app 서비스에 ports: ["3030:3000"]이 있다면 reverse_proxy app:3000을 사용하세요. 같은 Docker 네트워크의 컨테이너는 포트를 게시하지 않고도 서로 도달할 수 있으므로, 보통 앱에 ports: 항목이 전혀 필요 없어요.

플러그인이 있는 커스텀 Caddy 빌드가 필요하다면 Docker 빌드 지침을 따라 커스텀 Docker 이미지를 만들어요. compose.yml 옆에 Dockerfile을 만들고, compose.yml의 image: 줄을 build: .로 바꿔요.

사용

그러면 컨테이너를 시작할 수 있어요:

docker compose up -d

Caddyfile을 변경한 후 Caddy를 리로드하려면:

docker compose exec -w /etc/caddy caddy caddy reload

v2.11.0부터는 Caddy가 caddy run과 설정 파일로 시작된 경우 SIGUSR1로 리로드할 수 있어요:

docker compose kill -sUSR1 caddy

Caddy의 가장 최근 로그 1000개를 보고 follow로 새 로그가 스트리밍되는 것을 보려면:

docker compose logs caddy -n=1000 -f

Docker로 로컬 HTTPS

개발용 HTTPS로 Docker를 사용할 때 localhost나 app.localhost 같은 호스트 이름을 사용할 수 있어요. 이러면 Caddy의 로컬 CA로 인증서를 발급하는 로컬 HTTPS가 활성화돼요. 즉 컨테이너 밖의 HTTP 클라이언트는 Caddy가 서빙하는 TLS 인증서를 신뢰하지 않을 거예요. 이를 해결하려면 호스트 머신의 신뢰 저장소에 Caddy의 루트 CA 인증서를 설치하면 돼요:

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /usr/local/share/ca-certificates/root.crt \
  && sudo update-ca-certificates

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    /tmp/root.crt \
  && sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /tmp/root.crt

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    %TEMP%/root.crt \
  && certutil -addstore -f "ROOT" %TEMP%/root.crt

많은 웹 브라우저가 이제 자체 신뢰 저장소를 사용하므로(시스템의 신뢰 저장소 무시), 위 명령에서 컨테이너에서 복사한 root.crt 파일을 사용해 거기에도 인증서를 수동으로 설치해야 할 수 있어요.

Firefox의 경우 Preferences > Privacy & Security > Certificates > View Certificates > Authorities > Import로 가서 root.crt 파일을 선택하세요.
Chrome의 경우 Settings > Privacy and security > Security > Manage certificates > Authorities > Import로 가서 root.crt 파일을 선택하세요.

더 알아보기 (Learn more)

Caddy 공식 문서

Caddy 계속 실행하기