서버에 디스크 용량이 부족해지거나, 백업 스크립트가 실패하거나, 스마트홈 센서가 이상 값을 감지했을 때 — 이런 이벤트를 즉시 스마트폰으로 받아볼 수 있다면 얼마나 편할까요? 상용 푸시 알림 서비스는 무료 티어 제한이 있고, 메일 알림은 묻히기 일쑤입니다. 오늘 소개할 ntfy(발음: notify)는 HTTP PUT/POST 한 줄이면 스마트폰에 즉시 알림을 보내주는 오픈소스 푸시 알림 서버입니다. Docker 한 줄이면 설치가 끝나고, curl 명령어 하나로 알림을 쏠 수 있어서 기존에 운영 중인 모든 자동화 도구와 찰떡궁합입니다.
이 글에서는 ntfy를 Docker로 설치하고, 스마트폰 앱을 연결하고, 실제 업무·서버 관리에 바로 적용할 수 있는 실전 활용법까지 단계별로 안내합니다.
ntfy란 무엇인가 – 핵심 개념 이해
ntfy는 Go 언어로 작성된 경량 HTTP 기반 pub-sub 알림 서버입니다. 2022년에 처음 공개된 이후 GitHub 스타 2만 개를 넘기며 셀프호스팅 커뮤니티에서 꾸준히 사랑받고 있습니다. 핵심 철학은 단순함입니다. 복잡한 SDK나 클라이언트 라이브러리 없이, 어떤 프로그래밍 언어에서든 HTTP 요청 한 줄이면 알림을 보낼 수 있습니다.
동작 원리
ntfy의 동작은 놀라울 정도로 간단합니다. 서버에 ‘토픽(topic)’이라는 채널을 만들고, 그 토픽을 구독(subscribe)하는 클라이언트(스마트폰 앱, 웹 브라우저 등)가 있으면 됩니다. 누군가 해당 토픽에 메시지를 발행(publish)하면, 구독 중인 모든 클라이언트가 즉시 푸시 알림을 받습니다.
- 발행(Publish):
curl -d "서버 백업 완료" ntfy.example.com/my-alerts— 이게 전부입니다 - 구독(Subscribe): 스마트폰 앱에서 토픽 URL을 추가하면 자동으로 알림 수신
- 프로토콜: 표준 HTTP(S) — 방화벽 친화적이고 어디서든 동작
왜 ntfy인가 – 대안과의 비교
비슷한 역할을 하는 도구들과 비교해보면 ntfy의 장점이 명확합니다.
- 이메일 알림: 스팸함에 묻히거나 확인이 늦음. ntfy는 스마트폰 잠금화면에 즉시 표시
- Slack/Discord 웹훅: 해당 앱을 설치해야 하고, 채팅 알림에 묻힘. ntfy는 전용 알림 채널
- Pushover(유료): 1회 결제 $5. ntfy는 완전 무료 + 셀프호스팅으로 데이터 주권 확보
- Gotify: 유사한 셀프호스팅 도구지만 iOS 미지원. ntfy는 Android·iOS 모두 공식 지원
- Firebase/APNs 직접 연동: 개발 복잡도 높음. ntfy는 인프라를 추상화해 curl 한 줄로 해결
Docker로 ntfy 서버 설치하기
ntfy는 단일 바이너리로도 실행 가능하지만, 기존에 Docker 환경을 운영하고 있다면 컨테이너로 띄우는 것이 관리가 편합니다. 아래는 docker-compose를 사용한 설치 방법입니다.
사전 준비
- Docker와 Docker Compose가 설치된 서버 (NAS, 미니PC, VPS 등 어디든 가능)
- 알림을 수신할 스마트폰 (Android 또는 iOS)
- (선택) 리버스 프록시 설정을 위한 도메인
docker-compose.yml 작성
원하는 디렉토리에 docker-compose.yml 파일을 만듭니다.
version: "3"
services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
command: serve
ports:
- "8090:80"
volumes:
- ./cache:/var/cache/ntfy
- ./config:/etc/ntfy
environment:
- TZ=Asia/Seoul
restart: unless-stopped
여기서 8090:80은 호스트의 8090 포트를 컨테이너의 80 포트에 매핑한 것입니다. 이미 8090을 쓰고 있다면 다른 포트로 바꾸면 됩니다.
서버 설정 파일 생성
./config/server.yml 파일을 만들어 기본 설정을 잡아줍니다.
base-url: "http://ntfy.example.com"
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "48h"
behind-proxy: true
attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "1G"
attachment-file-size-limit: "15M"
각 설정의 의미를 살펴보겠습니다.
- base-url: 외부에서 접근할 URL. 도메인이 없으면 IP:포트로 지정
- cache-file: 메시지를 임시 저장하는 SQLite DB 경로. 앱이 오프라인이었다가 다시 접속하면 놓친 메시지를 가져감
- cache-duration: 메시지 보관 기간. 48시간이면 대부분의 시나리오에서 충분
- behind-proxy: Nginx/Caddy 뒤에서 운영할 경우 true로 설정
- attachment-*: 파일 첨부 기능 활성화. 스크린샷이나 로그 파일을 알림과 함께 보낼 수 있음
컨테이너 실행
docker compose up -d 명령으로 컨테이너를 시작합니다. 정상적으로 실행되면 http://서버IP:8090으로 접속했을 때 ntfy 웹 인터페이스가 나타납니다. 웹 인터페이스에서 직접 토픽을 구독하고 테스트 메시지를 보내볼 수도 있습니다.
첫 번째 알림 보내기
터미널에서 다음 명령어를 실행해보세요.
curl -d "ntfy 설치 성공! 🎉" http://localhost:8090/test-topic
웹 인터페이스에서 test-topic을 구독하고 있었다면 즉시 메시지가 나타납니다. 이것이 ntfy의 전부입니다 — HTTP POST 한 줄이면 알림이 전달됩니다.
스마트폰 앱 연결과 구독 설정
서버를 설치했으니 이제 스마트폰에서 알림을 받을 차례입니다.
앱 설치
- Android: Google Play Store 또는 F-Droid에서 “ntfy” 검색 → 설치
- iOS: App Store에서 “ntfy” 검색 → 설치 (2024년부터 공식 iOS 앱 제공)
셀프호스팅 서버 등록
앱을 열면 기본적으로 ntfy.sh(공식 공용 서버)에 연결됩니다. 셀프호스팅 서버를 사용하려면 설정에서 기본 서버 URL을 변경해야 합니다.
- 앱 설정(Settings) → Default server →
http://서버IP:8090또는 도메인 입력 - HTTPS를 설정한 경우
https://ntfy.example.com으로 지정
토픽 구독하기
앱 하단의 + 버튼을 눌러 토픽을 추가합니다. 토픽 이름은 자유롭게 정할 수 있습니다. 추천하는 토픽 구성 예시:
- server-alerts: 서버 장애·디스크·메모리 경고
- backup-status: 백업 성공/실패 알림
- home-events: 스마트홈 이벤트 (도어센서, 온습도 이상 등)
- cron-results: 정기 실행 스크립트 결과 보고
- deploy-notify: 배포 완료/실패 알림
토픽을 구독하면 해당 토픽으로 발행되는 모든 메시지가 스마트폰 푸시 알림으로 도착합니다. 알림 소리, 진동, 우선순위별 동작을 토픽마다 개별 설정할 수 있어서 중요도에 따라 차등 관리가 가능합니다.
실전 활용 시나리오 7가지
ntfy의 진가는 다른 도구들과 연동할 때 드러납니다. HTTP 요청만 보낼 수 있으면 무엇이든 ntfy와 연결할 수 있습니다. 실제로 유용한 7가지 시나리오를 소개합니다.
1. 셸 스크립트 완료 알림
오래 걸리는 작업(대용량 파일 변환, 데이터 마이그레이션 등)의 끝에 알림을 추가합니다.
#!/bin/bash
rsync -avz /data /backup/data
if [ $? -eq 0 ]; then
curl -H "Priority: low" -H "Tags: white_check_mark" -d "백업 완료: $(date '+%Y-%m-%d %H:%M')" http://ntfy.local:8090/backup-status
else
curl -H "Priority: urgent" -H "Tags: x" -d "백업 실패! 즉시 확인 필요" http://ntfy.local:8090/backup-status
fi
Priority 헤더로 알림 긴급도를 조절할 수 있습니다. urgent는 소리와 진동을 동반하고, low는 조용히 알림 센터에만 표시됩니다.
2. 디스크 용량 모니터링
cron에 등록해두면 디스크가 가득 차기 전에 미리 알려줍니다.
#!/bin/bash
THRESHOLD=85
USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ $USAGE -gt $THRESHOLD ]; then
curl -H "Priority: high" -H "Title: 디스크 경고" \
-d "루트 파티션 사용률: ${USAGE}% (임계값: ${THRESHOLD}%)" \
http://ntfy.local:8090/server-alerts
fi
이 스크립트를 crontab -e에서 */30 * * * *(30분마다)로 등록하면 디스크 상태를 자동 감시합니다.
3. Uptime Kuma 연동
이미 Uptime Kuma로 서비스 상태를 모니터링하고 있다면, 알림 채널로 ntfy를 추가할 수 있습니다. Uptime Kuma 설정 → Notifications → Add Notification에서:
- Notification Type: ntfy 선택
- Server URL:
http://ntfy.local:8090 - Topic:
server-alerts - Priority:
high
설정 후 모니터링 대상이 다운되면 스마트폰에 즉시 알림이 옵니다. 이메일보다 훨씬 빠르고 확실합니다.
4. n8n 워크플로우 알림
n8n에서 HTTP Request 노드를 사용해 워크플로우 결과를 알릴 수 있습니다. 예를 들어 매일 아침 뉴스를 크롤링하는 워크플로우의 마지막에 ntfy 노드를 추가하면:
- Method: POST
- URL:
http://ntfy.local:8090/daily-digest - Headers:
Title: 오늘의 뉴스 요약,Tags: newspaper - Body: 크롤링 결과 요약 텍스트
5. Home Assistant 연동
Home Assistant의 RESTful Notification을 사용해 스마트홈 이벤트를 ntfy로 보낼 수 있습니다. configuration.yaml에 추가:
notify:
- name: ntfy
platform: rest
resource: http://ntfy.local:8090/home-events
method: POST_JSON
data:
priority: 3
tags: ["house"]
이후 자동화에서 service: notify.ntfy를 호출하면 됩니다. 현관문이 열렸거나, 실내 온도가 설정 범위를 벗어나는 등의 이벤트를 즉시 알림으로 받을 수 있습니다.
6. GitHub Actions / CI 파이프라인
배포 파이프라인의 마지막 단계에 ntfy 알림을 추가하면 배포 완료를 실시간으로 확인할 수 있습니다.
- name: Notify deployment
if: always()
run: |
STATUS=${{ job.status }}
curl -H "Title: 배포 ${STATUS}" \
-H "Tags: ${STATUS == 'success' && 'rocket' || 'rotating_light'}" \
-d "${{ github.repository }} - ${GITHUB_SHA::7}" \
https://ntfy.example.com/deploy-notify
7. Python 스크립트 예외 알림
장시간 돌아가는 Python 스크립트에서 예외가 발생했을 때 즉시 알림을 받습니다.
import requests
def notify(message, priority="default", title=None):
headers = {"Priority": priority}
if title:
headers["Title"] = title
requests.post("http://ntfy.local:8090/server-alerts",
data=message.encode("utf-8"), headers=headers)
try:
# 오래 걸리는 작업
process_large_dataset()
notify("데이터 처리 완료", title="작업 성공")
except Exception as e:
notify(f"오류 발생: {e}", priority="urgent", title="긴급 확인 필요")
보안 설정 – 인증과 접근 제어
기본 설정에서는 누구나 토픽에 메시지를 보내고 구독할 수 있습니다. 로컬 네트워크 안에서만 사용한다면 괜찮지만, 외부에 노출하거나 민감한 알림을 다룬다면 인증을 설정해야 합니다.
사용자 인증 활성화
server.yml에 인증 관련 설정을 추가합니다.
auth-file: "/var/cache/ntfy/user.db"
auth-default-access: "deny-all"
auth-default-access: deny-all로 설정하면 인증 없이는 어떤 토픽에도 접근할 수 없습니다. 이후 사용자를 생성하고 권한을 부여합니다.
사용자 생성과 권한 설정
Docker 컨테이너 안에서 ntfy CLI를 사용해 사용자를 관리합니다.
# 관리자 사용자 생성
docker exec -it ntfy ntfy user add --role=admin admin-user
# 일반 사용자 생성 (읽기 전용 — 알림 수신만 가능)
docker exec -it ntfy ntfy user add reader-user
# 특정 토픽에 쓰기 권한 부여
docker exec -it ntfy ntfy access reader-user "server-alerts" read-only
# 스크립트용 쓰기 전용 계정
docker exec -it ntfy ntfy user add writer-bot
docker exec -it ntfy ntfy access writer-bot "server-alerts" write-only
토큰 기반 인증
비밀번호 대신 토큰을 사용하면 스크립트에서 더 안전하게 인증할 수 있습니다.
# 토큰 생성
docker exec -it ntfy ntfy token add writer-bot
# 토큰으로 알림 보내기
curl -H "Authorization: Bearer tk_생성된토큰" \
-d "인증된 알림" http://ntfy.local:8090/server-alerts
HTTPS 설정 (리버스 프록시)
외부 접근이 필요하다면 반드시 HTTPS를 설정해야 합니다. 이미 Nginx Proxy Manager나 Caddy를 운영하고 있다면, ntfy를 백엔드로 추가하면 됩니다. Nginx 설정 예시:
server {
listen 443 ssl;
server_name ntfy.example.com;
location / {
proxy_pass http://127.0.0.1:8090;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_connect_timeout 3600;
proxy_send_timeout 3600;
proxy_read_timeout 3600;
}
}
중요: ntfy는 WebSocket과 긴 HTTP 연결(Server-Sent Events)을 사용하므로 proxy_read_timeout을 충분히 길게 설정해야 합니다. 기본값 60초로 두면 구독 연결이 자주 끊어집니다.
고급 기능 활용
ntfy는 단순한 텍스트 알림을 넘어 다양한 고급 기능을 제공합니다.
알림에 액션 버튼 추가
알림에 버튼을 달아서 클릭 시 URL을 열거나 HTTP 요청을 보낼 수 있습니다.
curl -H "Actions: view, 로그 확인, https://grafana.local/dashboard; \
http, 서버 재시작, https://automation.local/restart, method=POST" \
-H "Title: 서버 응답 지연" \
-d "API 응답 시간이 5초를 초과했습니다" \
http://ntfy.local:8090/server-alerts
이렇게 하면 알림에 “로그 확인”과 “서버 재시작” 두 개의 버튼이 나타납니다. 장애 대응 시 스마트폰에서 바로 조치를 취할 수 있어 매우 유용합니다.
파일 첨부
로그 파일이나 스크린샷을 알림과 함께 보낼 수 있습니다.
# 파일 첨부
curl -T /var/log/error.log \
-H "Filename: error.log" \
-H "Title: 에러 로그" \
http://ntfy.local:8090/server-alerts
# 이미지 첨부 (스마트폰에서 미리보기 표시)
curl -T screenshot.png \
-H "Filename: screenshot.png" \
http://ntfy.local:8090/server-alerts
예약 알림 (Scheduled Delivery)
특정 시간에 알림을 받도록 예약할 수 있습니다.
# 30분 후에 알림
curl -H "Delay: 30m" -d "약 복용 시간입니다" http://ntfy.local:8090/reminders
# 특정 시각에 알림
curl -H "Delay: 2026-05-27T09:00:00+09:00" \
-d "월요일 아침 회의 10분 전" http://ntfy.local:8090/reminders
이모지 태그
Tags 헤더에 이모지 이름을 넣으면 알림 앞에 이모지가 표시됩니다. 시각적으로 알림 종류를 빠르게 구분할 수 있습니다.
Tags: white_check_mark→ ✅ 성공Tags: x→ ❌ 실패Tags: warning→ ⚠️ 경고Tags: rocket→ 🚀 배포Tags: house→ 🏠 홈이벤트
마크다운 본문
알림 본문에 마크다운을 사용할 수 있습니다(앱에서 렌더링 지원).
curl -H "Markdown: yes" -H "Title: 일일 리포트" \
-d "## 서버 상태 요약
- CPU: 23%
- 메모리: 68%
- 디스크: 45%
**모든 서비스 정상 가동 중**" \
http://ntfy.local:8090/daily-digest
운영 팁과 베스트 프랙티스
ntfy를 실무에서 안정적으로 운영하기 위한 팁을 정리합니다.
토픽 명명 규칙
토픽 이름은 누구나 추측할 수 없도록 충분히 구체적으로 짓되, 관리가 편하도록 일관된 규칙을 사용합니다.
homelab-서비스명-알림유형형태 권장 (예:homelab-nas-disk,homelab-docker-deploy)- 공용 ntfy 서버를 쓴다면 UUID를 포함시켜 충돌 방지 (예:
abc123-server-alerts) - 셀프호스팅이면 간결한 이름으로 충분 (인증으로 보호되므로)
알림 피로도 관리
너무 많은 알림은 오히려 중요한 알림을 놓치게 만듭니다.
- 우선순위 체계 수립: urgent(즉시 확인), high(1시간 내), default(참고), low(무음)
- 앱 설정에서 토픽별 알림 동작 분리: urgent만 소리+진동, 나머지는 무음 배너
- 반복 알림 억제: 같은 이슈로 반복 알림이 가지 않도록 스크립트에 쿨다운 로직 추가
- 일일 요약으로 전환: 빈도가 높은 정보성 알림은 하루에 한 번 모아서 보내기
백업과 데이터 보존
ntfy의 데이터는 /var/cache/ntfy/에 SQLite DB로 저장됩니다. docker-compose에서 이 경로를 볼륨 마운트해두었으므로 호스트에서 주기적으로 백업하면 됩니다. 다만 ntfy는 메시지를 영구 보관하는 용도가 아니라 전달 도구이므로, 정말 중요한 로그는 별도 저장소(Grafana Loki, 파일 등)에 남기고 ntfy는 알림만 담당하게 하는 것이 올바른 아키텍처입니다.
모니터링 대상에 ntfy 자체도 포함
Uptime Kuma에 ntfy 서버 자체의 헬스체크도 등록해두세요. http://ntfy.local:8090/v1/health 엔드포인트를 모니터링하면 됩니다. 물론 ntfy가 다운되면 Uptime Kuma의 ntfy 알림도 못 가니, 이때는 이메일이나 텔레그램을 백업 채널로 설정합니다.
공용 서버 vs 셀프호스팅 — 어떤 것을 선택할까
ntfy는 공식 공용 서버(ntfy.sh)를 무료로 제공합니다. 셀프호스팅과 공용 서버의 차이를 정리합니다.
- 공용 서버 장점: 설치 불필요, 즉시 사용 가능, 서버 관리 부담 없음
- 공용 서버 단점: 토픽 이름이 겹칠 수 있음(UUID 필요), 첨부파일 크기 제한 엄격, 메시지 보관 12시간, rate limit 존재
- 셀프호스팅 장점: 완전한 데이터 주권, 무제한 사용, 커스텀 보관 정책, LAN 내 초저지연
- 셀프호스팅 단점: 서버 관리 필요, 외부 접근 시 도메인+HTTPS 설정 필요
이미 Docker 환경이 있고 NAS나 홈서버를 운영하고 있다면 셀프호스팅을 강력 추천합니다. 리소스 소모가 매우 적어(메모리 30MB 이하) 다른 컨테이너와 함께 운영해도 부담이 없습니다.
마무리 – 알림 인프라의 시작점
ntfy는 “서버에 무슨 일이 생기면 내 폰으로 알려줘”라는 단순한 욕구를 가장 깔끔하게 해결해주는 도구입니다. 설치는 Docker 한 줄, 알림 발송은 curl 한 줄 — 이보다 더 간단할 수 없습니다. 하지만 이 단순함 위에 인증, 첨부파일, 액션 버튼, 예약 전송 등 실무에 필요한 기능이 모두 갖춰져 있어서 가벼운 개인 알림부터 팀 운영 알림까지 확장할 수 있습니다.
이미 Uptime Kuma, n8n, Home Assistant 등을 운영하고 있다면 ntfy를 알림 허브로 묶어보세요. 흩어져 있던 알림이 스마트폰 한 곳으로 모이면, 시스템 상태를 파악하는 속도가 확연히 달라집니다. 오늘 설치하고, 디스크 용량 경고 스크립트 하나만 연결해보면 — 그 편리함에 금세 다른 이벤트도 하나씩 추가하게 될 겁니다.
이미지는 Leonardo AI 로 생성되었습니다.
이미지는 Claude AI 로 생성되었습니다.