Pulse Docker 설치 가이드: Proxmox, Docker, Kubernetes 통합 모니터링 ⋆ Blog * JackerLab

개요

Pulse는 Proxmox VE, Docker, Kubernetes를 하나의 대시보드에서 모니터링하는 현대적인 플랫폼입니다. AI 기반 인사이트, 스마트 알림, 아름다운 UI를 제공하며, 복잡한 Prometheus + Grafana 스택 없이 홈랩부터 MSP까지 “단일 창(Single Pane of Glass)” 모니터링을 실현합니다.

항목	내용
GitHub	https://github.com/rcourtman/Pulse
Docker Hub	https://hub.docker.com/r/rcourtman/pulse
라이브 데모	https://demo.pulserelay.dev
라이선스	MIT
개발 언어	Go

Pulse란?

Pulse는 Proxmox를 위해 처음부터 설계된 모니터링 도구입니다. Proxmox API를 직접 이해하고, 노드, VM, LXC, 스토리지를 자동으로 매핑합니다. 여기에 Docker와 Kubernetes 모니터링까지 추가하여 홈랩의 모든 인프라를 하나의 대시보드에서 관리할 수 있습니다.

아키텍처

┌─────────────────────────────────────────────────────────────┐
│                     Pulse Server                             │
│   (웹 UI + API + 알림 + AI 분석)                            │
│                         ↑                                    │
├─────────────────────────────────────────────────────────────┤
│   Proxmox VE    │  Proxmox BS   │    Docker    │    K8s    │
│   (API 연결)    │  (API 연결)   │   (Agent)    │  (Agent)  │
└─────────────────────────────────────────────────────────────┘

Proxmox VE/PBS/PMG: API 토큰으로 직접 연결
Docker/Podman: 경량 Agent 설치
Kubernetes: Agent 또는 Helm 차트

핵심 철학

"Proxmox를 위해 설계된 모니터링"
- 단일 컨테이너로 전체 인프라 모니터링
- 자동 검색으로 즉시 시작
- 최소 리소스 사용
- AI 기반 문제 분석 (Pulse Patrol)

주요 기능

통합 모니터링

플랫폼	지원 기능
Proxmox VE	노드, VM, LXC, 스토리지, 클러스터
Proxmox Backup Server	백업 작업, 스냅샷, 스토리지
Proxmox Mail Gateway	메일 볼륨, 스팸 트렌드, 격리
Docker/Podman	컨테이너, Swarm 서비스
Kubernetes	클러스터, 노드, 파드, 서비스

모니터링 메트릭

카테고리	메트릭
CPU	사용률, 코어별 통계
메모리	사용량, 스왑
디스크	용량, I/O, S.M.A.R.T.
네트워크	대역폭, 트래픽
온도	CPU, GPU, 시스템 센서
VM/LXC	상태, 리소스, 업타임
컨테이너	CPU, 메모리, 네트워크, 헬스체크
백업	작업 상태, 스냅샷 히스토리

스마트 알림

기능	설명
적응형 임계값	Hysteresis 기반 트리거/클리어
알림 히스토리	타임라인 분석, 확인 마커
다중 채널	Discord, Slack, Telegram, Email, Gotify 등
에스컬레이션	단계별 알림 확대

AI 기능 (Pulse Patrol)

기능	설명
BYOK	OpenAI, Ollama 등 자체 키 사용
문제 분석	로그 분석, 근본 원인 파악
예측	스토리지 고갈 예측, ZFS 성능 저하
자동 수정	Pulse Pro에서 자동 문제 해결

Pulse Patrol이 감지하는 문제들:

백업 작업 실패
ZFS 풀 성능 저하
컨테이너 재시작 루프
설정 드리프트
스토리지 용량 부족 예측

추가 기능

기능	설명
자동 검색	네트워크에서 Proxmox 노드 자동 발견
클러스터 지원	하나의 노드 설정으로 전체 클러스터 모니터링
메트릭 히스토리	설정 가능한 보존 기간
백업 탐색기	백업 작업 시각화
Guest URL	VM/LXC 웹 UI 바로가기
설정 내보내기/가져오기	암호화된 설정 백업
자동 업데이트	안전한 롤백 지원
다크/라이트 테마	반응형 UI

모니터링 도구 비교

기능	Pulse	Beszel	Netdata	Prometheus+Grafana
Proxmox 네이티브	✅	❌	❌	❌
PBS 지원	✅	❌	❌	수동 설정
Docker 모니터링	✅	✅	✅	✅
Kubernetes	✅	❌	✅	✅
자동 검색	✅	❌	❌	❌
AI 분석	✅	❌	❌	❌
설정 복잡도	매우 쉬움	쉬움	쉬움	복잡
리소스 사용	낮음	매우 낮음	중간	높음
알림	✅	✅	✅	✅
상태 페이지	❌	❌	❌	❌

선택 가이드

상황	추천
Proxmox + Docker 홈랩	Pulse
Proxmox Backup Server 모니터링	Pulse
순수 Docker/서버 모니터링	Beszel
실시간 상세 메트릭	Netdata
엔터프라이즈 풀스택	Prometheus + Grafana
AI 기반 문제 분석	Pulse

시스템 요구 사항

Pulse Server

항목	최소	권장
CPU	1 Core	2 Core
RAM	128MB	256MB
저장소	100MB	500MB+ (히스토리)
포트	7655	–

Docker Agent

항목	사용량
RAM	~20MB
CPU	최소

Docker 설치

방법 1: 기본 설치 (가장 간단)

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul

volumes:
  pulse_data:

실행:

mkdir -p ~/pulse && cd ~/pulse

# docker-compose.yml 생성 후
docker compose up -d

# Bootstrap 토큰 확인 (첫 설정용)
docker exec pulse cat /data/.bootstrap_token

접속: http://localhost:7655

Bootstrap 토큰으로 첫 관리자 계정을 생성합니다.

방법 2: 인증 사전 설정

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      # API 토큰 (Agent 연결용)
      - API_TOKEN=your_api_token_here

volumes:
  pulse_data:

💡 평문 비밀번호는 시작 시 자동으로 bcrypt 해시됩니다.

방법 3: 네트워크 검색 범위 지정

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      # Proxmox 자동 검색 범위
      - DISCOVERY_SUBNET=192.168.1.0/24

volumes:
  pulse_data:

방법 4: HTTPS 활성화

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    init: true  # HTTPS 사용 시 필수
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
      - ./certs:/certs:ro
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      - HTTPS_ENABLED=true
      - TLS_CERT_FILE=/certs/cert.pem
      - TLS_KEY_FILE=/certs/key.pem

volumes:
  pulse_data:

⚠️ HTTPS 사용 시 init: true를 반드시 설정하세요. 좀비 프로세스 방지를 위해 필요합니다.

방법 5: Traefik 연동

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      - PULSE_PUBLIC_URL=https://pulse.example.com
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pulse.rule=Host(`pulse.example.com`)"
      - "traefik.http.routers.pulse.entrypoints=websecure"
      - "traefik.http.routers.pulse.tls.certresolver=letsencrypt"
      - "traefik.http.services.pulse.loadbalancer.server.port=7655"

volumes:
  pulse_data:

networks:
  traefik_network:
    external: true

방법 6: AI 기능 (Pulse Patrol) 활성화

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      # OpenAI 사용
      - OPENAI_API_KEY=sk-xxxxxxxx
      # 또는 Ollama 사용
      # - OLLAMA_BASE_URL=http://ollama:11434

volumes:
  pulse_data:

방법 7: 읽기 전용 모드 (대시보드 전용)

# docker-compose.yml
services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Asia/Seoul
      - PULSE_AUTH_USER=admin
      - PULSE_AUTH_PASS=your_secure_password
      # Docker 업데이트 버튼 숨김
      - PULSE_DISABLE_DOCKER_UPDATE_ACTIONS=true

volumes:
  pulse_data:

환경 변수

인증

변수	설명	예시
`PULSE_AUTH_USER`	관리자 사용자명	`admin`
`PULSE_AUTH_PASS`	관리자 비밀번호 (자동 해시)	`password123`
`API_TOKEN`	Agent용 API 토큰	`your-token`
`API_TOKENS`	다중 API 토큰 (쉼표 구분)	`token1,token2`

네트워크

변수	설명	기본값
`DISCOVERY_SUBNET`	Proxmox 자동 검색 범위	`192.168.0.0/24`
`PULSE_PUBLIC_URL`	공개 URL (알림, OIDC용)	–
`PULSE_AGENT_CONNECT_URL`	Agent 연결용 URL	–
`CORS_ALLOWED_ORIGIN`	CORS 허용 오리진	동일 오리진

HTTPS

변수	설명
`HTTPS_ENABLED`	HTTPS 활성화
`TLS_CERT_FILE`	인증서 파일 경로
`TLS_KEY_FILE`	키 파일 경로

기타

변수	설명	기본값
`TZ`	타임존	`UTC`
`LOG_LEVEL`	로그 레벨	`info`
`PULSE_DATA_DIR`	데이터 디렉토리	`/data`
`PULSE_DISABLE_DOCKER_UPDATE_ACTIONS`	Docker 업데이트 비활성화	`false`
`PULSE_DISABLE_DOCKER_UPDATE_CHECKS`	Docker 업데이트 체크 비활성화	`false`

초기 설정

1) 첫 접속

URL: http://localhost:7655

Bootstrap 토큰 방식 (권장):

토큰 확인: docker exec pulse cat /data/.bootstrap_token
웹 UI에서 토큰 입력
관리자 계정 생성

환경 변수 방식:

PULSE_AUTH_USER와 PULSE_AUTH_PASS 설정 시 자동 로그인

2) Proxmox VE 노드 추가

자동 검색:

Settings → Proxmox VE → Auto-Discovery
검색된 노드 선택 → Add

수동 추가:

Settings → Proxmox VE → +Add PVE Node
Node Name, Host URL 입력
생성된 스크립트 복사
Proxmox 노드 쉘에서 실행:

# Proxmox 노드에서 실행
curl -fsSL http://pulse-server:7655/install.sh | bash -s -- --pve

3) Proxmox Backup Server 추가

Settings → PBS Nodes → +Add PBS Node
Host URL, 인증 정보 입력
또는 스크립트로 설치

4) Docker 호스트 추가

방법 A: Agent 설치 (권장)

# Docker 호스트에서 실행
curl -fsSL http://pulse-server:7655/install-container-agent.sh | \
  bash -s -- --url http://pulse-server:7655 --token your-api-token

방법 B: Agent를 컨테이너로 실행

# docker-compose.yml (Docker 호스트)
services:
  pulse-agent:
    image: ghcr.io/rcourtman/pulse-docker-agent:latest
    container_name: pulse-agent
    restart: unless-stopped
    pid: host
    uts: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - PULSE_URL=http://pulse-server:7655
      - PULSE_TOKEN=your-api-token

5) Kubernetes 클러스터 추가

# Helm 설치
helm repo add pulse https://rcourtman.github.io/Pulse
helm repo update

helm upgrade --install pulse pulse/pulse \
  --namespace pulse \
  --create-namespace

알림 설정

알림 채널 추가

Settings → Notifications에서 설정:

채널	설정
Email	SMTP 서버 설정
Discord	Webhook URL
Slack	Webhook URL
Telegram	Bot Token, Chat ID
Gotify	Server URL, Token
Microsoft Teams	Webhook URL

알림 규칙

Settings → Alert Configuration:

리소스별 임계값: CPU, 메모리, 디스크 사용률
상태 알림: VM/LXC 다운, 컨테이너 재시작
백업 알림: 백업 실패, 스토리지 부족

Pulse Patrol (AI 분석)

설정

Settings → AI → Pulse Patrol:

AI 제공자 선택 (OpenAI, Ollama 등)
API 키 입력
분석 주기 설정 (10분 ~ 7일)

감지 가능한 문제

카테고리	예시
백업	“최근 3회 백업 실패, PBS 연결 확인 필요”
스토리지	“현재 성장률로 3일 후 풀 용량 도달”
ZFS	“ZFS 80% 이상에서 성능 저하 예상”
컨테이너	“컨테이너 재시작 루프 감지”

Pulse Pro

유료 버전에서는 자동 수정(Auto-Fix) 기능을 제공합니다.

업데이트

cd ~/pulse

# 최신 이미지
docker compose pull

# 재시작
docker compose up -d

# 로그 확인
docker compose logs -f pulse

특정 버전 사용:

services:
  pulse:
    image: rcourtman/pulse:v4.22.0
    # ...

트러블슈팅

Proxmox 연결 실패

API 토큰 확인:

# Proxmox에서 API 토큰 확인
pveum user token list root@pam

방화벽 확인:

# Proxmox 포트 8006 접근 가능한지 확인
curl -k https://proxmox-ip:8006

Docker Agent 연결 실패

Agent 상태 확인:

# Agent 로그
docker logs pulse-agent

# 연결 테스트
curl http://pulse-server:7655/api/health

재등록 필요 시:

Settings → Docker → Removed Hosts → “Allow re-enroll”

VM 디스크 사용량이 0으로 표시됨

VM에 QEMU Guest Agent가 필요합니다:

# Linux VM에서
apt install qemu-guest-agent
systemctl enable qemu-guest-agent
systemctl start qemu-guest-agent

Proxmox에서 VM Options → QEMU Guest Agent 활성화 후 VM 재시작

로그가 너무 많음

environment:
  - LOG_LEVEL=warn  # info에서 warn으로 변경

인증 문제

# 설정 초기화
docker exec pulse rm /data/.env
docker restart pulse

# 새 Bootstrap 토큰으로 재설정
docker exec pulse cat /data/.bootstrap_token

보안

인증 방식

비밀번호 인증: 기본 방식
API 토큰: Agent, 자동화용
프록시 인증: Authentik, Authelia SSO 연동

SSO 연동

Settings → Security → Proxy Authentication:

environment:
  - PULSE_PROXY_AUTH_ENABLED=true
  - PULSE_PROXY_AUTH_HEADER=X-Forwarded-User

암호화

노드 자격 증명은 암호화되어 저장 (nodes.enc)
API 토큰은 해시되어 저장

권장 사항

HTTPS 사용 (프로덕션)
API 토큰은 용도별로 분리
.env 파일 권한 600으로 설정
정기적인 설정 백업

사용 사례

1. Proxmox 홈랩

여러 PVE 노드 통합 모니터링
PBS 백업 상태 시각화
VM/LXC 리소스 추적
스토리지 용량 알림

2. Docker + Proxmox 혼합 환경

Proxmox VM 위의 Docker 컨테이너 모니터링
단일 대시보드에서 전체 스택 확인
컨테이너 헬스체크 알림

3. MSP/다중 사이트

여러 클라이언트 인프라 모니터링
조직별 분리 (Pulse Pro)
중앙화된 알림 관리

4. Kubernetes 환경

K8s 클러스터 모니터링
파드, 서비스 상태 추적
Proxmox + K8s 통합 뷰

마무리

Pulse는 Proxmox를 위해 처음부터 설계된 모니터링 도구로, Docker와 Kubernetes까지 지원하는 통합 플랫폼입니다. 복잡한 Prometheus + Grafana 스택 없이 단일 컨테이너로 전체 인프라를 모니터링할 수 있습니다. AI 기반 Pulse Patrol은 문제를 사전에 감지하고 근본 원인을 분석합니다.

핵심 장점

장점	설명
Proxmox 네이티브	PVE, PBS, PMG 완벽 지원
통합 대시보드	Proxmox + Docker + K8s
자동 검색	네트워크에서 노드 자동 발견
AI 분석	문제 예측 및 근본 원인 분석
경량	단일 컨테이너, 최소 리소스
현대적 UI	반응형, 다크/라이트 테마

이런 분께 추천

Proxmox VE를 사용하는 홈랩 운영자
Proxmox + Docker 혼합 환경
PBS 백업 모니터링이 필요한 분
복잡한 모니터링 스택이 부담스러운 분
AI 기반 문제 분석이 필요한 분

개요