ntfy: 셀프호스팅 푸시 알림 서버

curl -d "메시지" ntfy.sh/토픽이름 명령 한 줄이면 스마트폰에 바로 알림이 도착해요. 셸 스크립트나 cron 작업이 끝났을 때, 백업이 실패했을 때, 홈서버에 특정 이벤트가 발생했을 때 알림을 받고 싶은 상황은 흔한데, ntfy는 이런 요구를 극도로 단순하게 해결해주는 셀프호스팅 푸시 알림 서버예요. 그럼 ntfy로 셀프호스팅 푸시 알림 서버를 어떻게 구축할 수 있을까요?

사용법이 이렇게 단순할 수 있나

ntfy의 핵심 사용법은 정말로 이게 전부예요.

curl -d "백업이 완료되었습니다" ntfy.sh/my-unique-topic-name

이 명령 한 줄만 실행하면 my-unique-topic-name이라는 토픽을 구독 중인 모든 기기(스마트폰 앱, 브라우저, 데스크톱)에 즉시 알림이 도착해요. 별도의 API 키 발급이나 계정 생성 없이, 그냥 원하는 토픽 이름을 URL 경로로 정하기만 하면 바로 사용할 수 있어요(공용 서버인 ntfy.sh 기준이고, 이 글에서 다룰 건 이걸 직접 셀프호스팅하는 방법이에요).

왜 셀프호스팅해야 하는가

공용 ntfy.sh 서버를 그냥 써도 되지만, 다음과 같은 이유로 직접 운영하는 걸 고려할 만해요.

토픽 이름 충돌/노출 우려: 공용 서버에서는 토픽 이름을 아는 사람이면 누구나 구독하거나 메시지를 보낼 수 있어요. 셀프호스팅하면 내 서버에 접근 권한이 있는 사람만 이용 가능해요.
알림량 제한 없음: 공용 서버는 무료 사용량에 제한이 있을 수 있지만, 직접 운영하면 서버 자원이 허용하는 한 무제한이에요.
민감한 내용 포함 가능: 서버 로그, 보안 경고처럼 민감할 수 있는 내용도 내가 통제하는 인프라 안에서만 오가게 할 수 있어요.

실전 활용 예시

ntfy는 웹훅이나 알림 채널을 지원하는 거의 모든 도구에 붙일 수 있어서 활용 범위가 넓어요.

cron 작업 결과 알림: 스크립트 끝에 curl -d "작업 완료" http://내서버/backup-status 한 줄만 추가하면 끝
Uptime Kuma 알림 채널로 연동: Uptime Kuma가 지원하는 알림 채널 중 하나로 ntfy를 등록해 서비스 장애를 즉시 수신
홈 자동화 트리거: 현관문 센서가 열리면 Home Assistant가 ntfy로 알림을 보내도록 연동
CI/CD 파이프라인 완료 알림: Gitea Actions 같은 CI 파이프라인 마지막 단계에 ntfy 호출을 추가해 빌드 성공/실패를 바로 확인

우선순위와 액션 버튼

단순 텍스트 알림을 넘어, 메시지에 우선순위를 지정해 긴급한 알림은 다른 소리로 울리게 하거나 알림 자체에 클릭 가능한 액션 버튼(예: “서버 재시작”, “로그 확인 링크”)을 붙일 수도 있어요.

curl \
  -H "Priority: urgent" \
  -H "Actions: view, 대시보드 열기, https://내서버/dashboard" \
  -d "디스크 사용량이 90%를 초과했습니다" \
  http://내서버/alerts

이런 세밀한 제어 덕분에 단순 로그 출력용 알림부터 즉각 대응이 필요한 긴급 경보까지 하나의 시스템으로 관리할 수 있어요.

설치

다른 서비스들처럼 Docker Compose 한 파일로 간단히 띄울 수 있어요.

services:
  ntfy:
    image: binwiederhier/ntfy
    command: serve
    ports:
      - "80:80"
    volumes:
      - ntfy_cache:/var/cache/ntfy
      - ntfy_data:/var/lib/ntfy
volumes:
  ntfy_cache:
  ntfy_data:

모바일에서 알림을 받으려면 공식 ntfy 앱을 설치하고, 서버 주소를 내가 운영하는 셀프호스팅 인스턴스로 지정하면 돼요.

인증과 접근 제어

기본 설정은 누구나 토픽을 구독하고 게시할 수 있는 개방형 구조예요. 실제 운영 환경에서는 auth-default-access 설정을 deny-all로 바꾸고, 사용자 계정과 토픽별 읽기/쓰기 권한을 명시적으로 부여하는 게 안전해요. 특히 외부에 노출된 서버라면 이 설정을 반드시 확인해야 해요.

결론

ntfy는 “알림 보내기”라는 하나의 기능에 극도로 집중해 사용법을 최소화한 도구예요. 이미 운영 중인 다른 셀프호스팅 서비스나 개인 스크립트에 알림 기능을 추가하고 싶을 때, 별도의 복잡한 설정 없이 curl 한 줄로 바로 연결할 수 있다는 점이 실무에서 가장 크게 체감되는 장점이에요.