Uptime Kuma VPS 설치: Docker Compose, Caddy, 알림

Uptime Kuma는 HTTP(S), TCP, ping, DNS, WebSocket 등의 검사를 지원하는 오픈소스 자체 호스팅 모니터입니다. 별도의 VPS에서 실행하면 운영 서버가 다운될 때 함께 사라지지 않고 계속 검사를 수행합니다.

이 Uptime Kuma VPS 설치에서는 Docker Compose로 v2를 배포하고, 3001 포트를 루프백에 묶어 두고, Caddy로 HTTPS를 추가하고, 알림을 Telegram·Discord·Slack으로 보내고, 상태 페이지를 공개합니다.

사전 준비물과 필요한 것

최소 1 vCPU, 1 GB RAM, 10 GB 로컬 SSD 스토리지를 갖춘 VPS
Ubuntu 24.04 LTS 또는 Docker가 지원하는 다른 최신 Ubuntu 릴리스
VPS에 설치된 Docker Engine과 Docker Compose
A 레코드로 VPS를 가리키는 도메인 또는 서브도메인 (예: status.example.com)
SSH 접속 권한과 기본적인 커맨드라인 사용 능력

Docker가 아직 설치되어 있지 않다면 다음을 참고하세요: Docker의 Ubuntu 설치 가이드. Docker Engine과 아래에서 사용하는 Compose 플러그인을 설치합니다.

모니터링 VPS를 감시 대상과 분리해야 하는 이유

Production in Region A has failed and its website, API and database are down, while Uptime Kuma on a separate VPS in Region B stays online, keeps probing those services and routes alerts to Telegram, Discord and Slack. An external watchdog checks Uptime Kuma itself.

같은 서버에서 돌아가는 운영 환경과 모니터링은 동일한 장애 도메인을 공유합니다. 그 서버가 멈추면 애플리케이션과 알림을 보내야 할 시스템이 함께 사라집니다.

이를 개선하는 실용적인 구성이 두 가지 있습니다:

같은 제공업체, 다른 위치. 운영 환경과 모니터링을 서로 다른 위치의 별도 호스트에 두세요. 단일 서버나 단일 데이터센터 장애에 대한 노출은 줄어들지만, 제공업체 전체에 걸친 모든 네트워크 또는 컨트롤 플레인 장애까지 막아 주지는 않습니다.
완전히 다른 제공업체. 모니터를 다른 곳에 호스팅하면 제공업체 전체에 걸친 장애까지 방어할 수 있습니다. 대신 관리해야 할 계정과 청구서, 운영 대상이 하나씩 늘어납니다.

Uptime Kuma 인스턴스가 하나뿐이라면 여전히 외부 감시자가 없습니다. 공개 상태 페이지를 대상으로 외부 HTTP(S) 검사를 하나 추가하세요. UptimeRobot의 무료 플랜 현재 5분 간격의 모니터 50개를 제공합니다. 이것으로 Uptime Kuma가 고가용성이 되지는 않지만, 모니터 자체가 사라졌을 때 알려 줍니다.

공개 상태 페이지에도 같은 원칙이 적용됩니다. 장애를 알려 주는 쪽은 장애가 나는 쪽과 같은 장애 도메인에 있으면 안 됩니다.

루트 액세스, NVMe, AMD EPYC 성능을 갖춘 Linux VPS에서 개발하세요.

Linux 요금제 보기

VPS 사양 선택

Uptime Kuma에는 모니터 개수와 RAM을 연결하는 믿을 만한 공식이 없습니다. 부하가 모니터 종류, 검사 간격, 재시도 설정, 이력 보관 기간에 따라 달라지기 때문입니다. 단순한 HTTP(S), TCP, ping, DNS 검사는 Chromium을 띄우는 Browser Engine 검사보다 가볍습니다.

기본 검사를 몇 개만 돌린다면 1 vCPU, 1 GB RAM, 로컬 SSD 스토리지로 시작하세요. 실제 사용량은 다음으로 확인합니다: docker stats uptime-kuma 데이터베이스 증가량은 다음으로 확인합니다: du -sh /opt/uptime-kuma/data. 사용량이 계속 높거나, 컨테이너가 OOM kill을 보고하거나, Browser Engine 검사를 추가한다면 메모리를 늘리세요.

전체(full) v2 이미지에는 Chromium과 내장 MariaDB가 포함되어 있습니다. Docker 태그 문서 full 이미지와 slim 이미지의 차이는 Docker 태그 문서에 설명되어 있습니다.

Docker Compose로 Uptime Kuma 배포하기

이 파일을 /opt/uptime-kuma/ 아래에 docker-compose.yml로 저장하세요:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      # Bind to localhost only. The reverse proxy will expose it on 443.
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data

짚고 넘어갈 만한 세 줄이 있습니다:

image: louislam/uptime-kuma:2는 메이저 버전을 고정합니다. :2 태그는 안정 2.x 릴리스 라인을 따라갑니다. :latest는 쓰지 마세요.
127.0.0.1:3001:3001은 컨테이너를 localhost에만 바인딩합니다. 공용 인터넷이 3001 포트에 직접 닿아서는 안 됩니다. TLS 인증서와 공개 호스트명은 리버스 프록시가 보유합니다.
데이터 볼륨에는 데이터베이스, 모니터 설정, 이력이 담깁니다. 로컬 스토리지에 두세요. Uptime Kuma의 설치 문서 는 신뢰할 수 있는 POSIX 잠금을 지원하지 않는 파일 시스템(다수의 NFS 구성 포함)이 SQLite를 손상시킬 수 있다고 경고합니다. 파일 시스템 수준의 복사본을 뜨기 전에 스택을 정지하세요.

실행한 뒤 확인하세요:

sudo install -d -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
# Paste the docker-compose.yml file above.
sudo docker compose up -d
sudo docker compose ps

docker compose ps의 예상 출력:

NAME          IMAGE                       STATUS                   PORTS
uptime-kuma   louislam/uptime-kuma:2      Up (healthy)             127.0.0.1:3001->3001/tcp

대시보드에 처음 접속할 때는 3001 포트를 잠깐이라도 공용 인터넷에 열지 마세요. SSH 터널로 접속합니다:

ssh -L 3001:127.0.0.1:3001 [email protected]

브라우저에서 http://localhost:3001 을 열어 관리자 계정을 만들고, 강력한 비밀번호를 설정한 뒤 터널을 닫습니다. 이후로는 리버스 프록시를 거쳐 HTTPS로 대시보드에 접속하게 됩니다.

Compose를 직접 다룰 필요가 없다면, Uptime Kuma 원클릭 앱으로도 제공합니다. 현재 앱 페이지에는 v1이 표시되어 있어 이 가이드의 v2 Compose 구성과는 맞지 않습니다. 반드시 v2가 필요하다면 수동 Compose 방식을 쓰세요.

리버스 프록시와 TLS

Public traffic reaches Caddy on the host or an Nginx Proxy Manager container over HTTPS on port 443. Caddy forwards to Uptime Kuma on 127.0.0.1:3001 while the NPM container uses a shared Docker network instead. Public access to port 3001 is blocked, and first-time setup runs through an SSH tunnel to localhost:3001.

Uptime Kuma를 직접 노출하지 마세요. TLS, 올바른 URL 처리, 단일 공개 진입점을 위해 앞단에 리버스 프록시를 두세요. 방법은 두 가지입니다.

Caddy. Caddy가 아직 설치되어 있지 않다면 공식 Ubuntu 패키지 설치 절차를 따르세요. Caddy를 호스트 서비스로 실행하면, 아래 Caddyfile이 루프백의 Uptime Kuma로 프록시하고 인증서 발급과 갱신을 자동으로 처리합니다.

팁: 모니터링 VPS에 Uptime Kuma만 올라간다면 Caddy를 쓰세요. Caddyfile은 세 줄이면 되고, 인증서 발급과 갱신은 Caddy가 알아서 합니다. Certbot도, 새벽 4시에 챙겨야 하는 별도의 갱신 타이머도 필요 없습니다.

이 내용을 /etc/caddy/Caddyfile로 저장하세요:

status.example.com {
    reverse_proxy 127.0.0.1:3001
}

Caddy를 다시 불러옵니다:

sudo systemctl reload caddy

확인합니다:

curl -I https://status.example.com

유효한 인증서와 함께 2xx 또는 3xx 응답을 받아야 정상입니다. 연결이 실패한다면 도메인의 A 또는 AAAA 레코드가 이 VPS를 가리키는지, 80과 443 포트에 도달할 수 있는지, Caddy가 두 포트를 모두 바인딩할 수 있는지 확인하세요. 이는 모두 Caddy의 자동 HTTPS 요구 사항에 해당합니다..

Nginx Proxy Manager. NPM을 호스트에서 바로 실행 중이라면 status.example.com용 Proxy Host를 추가하고, 127.0.0.1의 3001 포트로 전달하고, Let's Encrypt 인증서를 요청하고, Websockets Support를 켜세요. NPM이 Docker에서 돌고 있다면 127.0.0.1은 NPM 컨테이너 자신을 가리킵니다. 그럴 때는 NPM과 Uptime Kuma를 같은 Docker 네트워크에 연결한 뒤, 프록시 호스트를 3001 포트의 uptime-kuma로 전달하세요.

알림 라우팅: Telegram, Discord, Slack

Uptime Kuma는 같은 모니터 이벤트를 여러 알림 채널로 보낼 수 있습니다. 각 제공자를 한 번만 설정해 두고, 누가 알림을 받아야 하는지에 따라 모니터마다 채널을 하나 이상 붙이면 됩니다.

알림은 다음 경로에서 전역으로 설정합니다: 설정 > 알림그런 다음 개별 모니터에 할당합니다. 모니터 하나가 채널 하나 또는 여러 개로 알림을 보낼 수 있습니다. 같은 알림이 당직 엔지니어에게는 Telegram으로, 팀에는 Slack으로, 감사 로그용으로는 이메일로 나갈 수 있고, 전부 하나의 이벤트에서 시작됩니다.

Telegram에서 다음에게 메시지를 보내세요: @BotFather 그리고 /newbot을 실행하세요. 이름과 사용자명을 정하면 BotFather가 봇 토큰을 알려 줍니다. 잘 보관하세요.
새로 만든 봇에 아무 메시지나 보내세요. 그런 다음 브라우저에서 https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates 을 엽니다. chat.id 필드를 찾으면 그것이 여러분의 chat ID입니다.
Uptime Kuma에서: 설정 > 알림 > 알림 설정 > Telegram. 봇 토큰과 chat ID를 붙여 넣으세요. 그런 다음 클릭: 테스트. 봇이 테스트 알림을 보내는지 확인하세요.
테스트 메시지가 오지 않는다면 봇 토큰과 chat ID가 맞는지 확인하고, VPS 방화벽이 api.telegram.org로 나가는 HTTPS를 허용하는지 점검하세요.

Discord

알림을 받을 Discord 서버를 여세요. 대상 채널을 우클릭한 다음 채널 편집 > 연동 > 웹후크 > 새 웹후크. 이름을 정하고(예: "Uptime Kuma"), 채널을 고른 뒤 웹후크 URL을 복사하세요.
Uptime Kuma에서: 설정 > 알림 > 알림 설정 > Discord. 웹후크 URL을 붙여 넣으세요. 원한다면 사용자명과 아바타도 지정할 수 있습니다.
클릭 테스트. 웹후크가 채널에 테스트 알림을 올리는지 확인하세요.

Slack

Slack에서 다음을 만드세요: Incoming Webhook 알림을 받을 채널용으로 만듭니다. Slack은 https://hooks.slack.com/services/T.../B.../.... 형태의 웹후크 URL을 돌려줍니다.
Uptime Kuma에서: 설정 > 알림 > 알림 설정 > Slack. 웹후크 URL을 붙여 넣으세요. 원한다면 아이콘과 채널 재지정도 설정할 수 있습니다.
클릭 테스트.

모든 테스트가 통과하면 각 모니터를 편집해 사용할 알림 채널을 선택하세요. 그리고 Max Retries(최대 재시도 횟수) 와 Retry Interval(재시도 간격) 짧은 실패 한 번으로 곧바로 알림이 울리지 않도록 설정하세요.

기본 제공 상태 페이지 (그리고 언제 부족해지는가)

Uptime Kuma에는 사용자 지정 슬러그, 모니터 그룹화, 사용자 도메인, 장애 공지, 예정된 점검 안내를 갖춘 공개 상태 페이지가 들어 있습니다. 인스턴스 하나에서 서비스별·대상별로 여러 개의 상태 페이지를 게시할 수도 있습니다.

더 큰 한계는 고객 커뮤니케이션 쪽입니다. 방문자가 상태 페이지에서 바로 이메일로 업데이트를 구독할 수 없고, 그 공개 페이지는 운영자 대시보드와 동일한 Uptime Kuma 애플리케이션의 일부로 남아 있습니다. 방문자 자가 구독은 여전히 미해결 기능 요청으로 남아 있습니다.

고객 구독 기능이나 모니터링 대시보드와 분리된 상태 시스템이 필요하다면 Kener가 하나의 대안입니다. 두 도구를 어떻게 함께 쓰는지는 자체 호스팅 모니터링 스택 글에서 설명합니다.

자주 겪는 문제

VPS 방화벽이 나가는 HTTPS를 막으면 알림이 조용히 실패합니다. 증상: Test 버튼이 어떤 채널에서는 되고 어떤 채널에서는 안 됩니다. 해결: 나가는 HTTPS 연결이 허용되어 있는지, VPS에서 curl -I https://api.telegram.org 가 성공하는지 확인하세요.

브라우저에 "ERR_TOO_MANY_REDIRECTS"가 표시됩니다 프록시를 켠 뒤에 이런 오류가 난다면, Caddy나 Nginx Proxy Manager, 또는 앞단 CDN에 HTTP→HTTPS 리다이렉트가 중복으로 걸려 있는지 확인하세요. Uptime Kuma는 3001 포트에서 계속 HTTP로 서비스하고, TLS 종료는 공개 리버스 프록시가 맡아야 합니다. 신뢰할 수 있는 프록시 헤더를 켠다면 현재 경로는 다음과 같습니다: 설정 > Reverse Proxy > HTTP Headers > Trust Proxy.

컨테이너가 몇 분마다 재시작됩니다. 컨테이너가 메모리 부족으로 종료된 것인지 확인한 다음, docker stats uptime-kuma로 현재 사용량을 지켜보세요. OOM으로 종료됐거나 메모리가 VPS 한계 근처에 머문다면 RAM을 늘리거나, 무거운 검사를 줄이거나, 검사 간격을 늘리세요.

상태 페이지가 localhost에서는 되는데 공개 호스트명으로는 안 됩니다. 리버스 프록시가 루트 경로를 그대로 전달하는지, Host 헤더를 보존하는지, WebSockets를 지원하는지 확인하세요. Uptime Kuma는 하위 디렉터리 설치를 지원하지 않으므로, example.com/uptime-kuma 같은 경로 대신 전용 도메인이나 서브도메인을 쓰세요.

마무리

별도의 VPS에서 돌리는 Uptime Kuma는 검사 항목, 알림 경로, 공개 상태 페이지에 대한 통제권을 주지만, 업데이트와 백업, OS 패치, 그리고 모니터 자체를 감시할 외부 워치독까지 여러분 몫이 됩니다. 운영 환경과 다른 위치의 VPS를 고르고, Docker Compose로 v2를 배포하거나 표기된 버전을 확인한 뒤 원클릭 앱을 쓰고, 앞단에 Caddy를 두고, 팀이 실제로 보는 채널에 연결하세요.

자주 묻는 질문

Uptime Kuma는 RAM이 얼마나 필요한가요?

Uptime Kuma에는 모니터 개수와 RAM을 연결하는 믿을 만한 공식이 없습니다. 사용량이 모니터 종류, 검사 간격, 재시도 설정, 이력 보관 기간, Browser Engine 사용 여부에 따라 달라지기 때문입니다. 기본 검사를 몇 개만 돌린다면 1 GB RAM으로 시작하고 docker stats uptime-kuma로 실제 사용량을 지켜보세요. 사용량이 한계 근처에 머물거나 컨테이너가 OOM으로 종료되면 메모리를 늘리면 됩니다.

Uptime Kuma를 앱과 같은 서버에서 돌려도 될까요?

아니요. 모니터링 도구와 애플리케이션이 서버를 공유하면, 서버 장애가 둘을 동시에 내려앉히고 가장 필요한 순간에 알림을 잃게 됩니다. Uptime Kuma는 별도의 VPS에서, 가능하면 다른 데이터센터에서 돌리세요.

Uptime Kuma가 Telegram, Discord, Slack으로 알림을 보낼 수 있나요?

네. Telegram, Discord, Slack은 이메일, 범용 웹후크, PagerDuty, ntfy, Mattermost 등과 함께 기본 제공되는 알림 서비스입니다. Telegram은 봇 토큰과 chat ID를 쓰고, Discord와 Slack은 웹후크 URL을 씁니다. 하나의 모니터에 여러 알림 채널을 붙일 수 있습니다.

Uptime Kuma와 UptimeRobot의 차이는 무엇인가요?

Uptime Kuma는 자체 호스팅이라 서버와 업데이트, 백업, 알림 경로를 직접 관리해야 합니다. 검사 간격은 20초까지 짧게 잡을 수 있습니다. UptimeRobot은 호스팅형 SaaS이고, 현재 무료 플랜에는 5분 간격 검사 모니터 50개가 포함됩니다. 통제권을 원하면 Uptime Kuma를, 모니터링 서버를 직접 운영하고 싶지 않으면 UptimeRobot을 고르세요.

Uptime Kuma에 공개 상태 페이지가 있나요?

있습니다. 어떤 모니터를 노출할지 고르고, 그룹으로 묶고, 여러 개의 상태 페이지를 게시하고, 사용자 도메인에 연결하고, 점검 안내를 예약할 수 있습니다. 방문자가 이메일로 직접 구독하는 기능은 내장되어 있지 않으므로, 고객이 업데이트를 구독해야 한다면 고객 대상 상태 페이지 도구를 따로 쓰세요.

VPS에 Uptime Kuma를 설치하는 방법