Homarr: 드래그앤드롭으로 만드는 홈 서버 대시보드 ⋆ Blog * JackerLab

YAML 없이 마우스만으로 꾸미는 직관적인 셀프호스팅 대시보드

개요

Homarr는 코딩 없이 드래그앤드롭만으로 홈 서버 대시보드를 만들 수 있는 오픈소스 프로젝트입니다. 노션이나 트렐로처럼 직관적인 UI로 서비스를 추가하고, 30개 이상의 통합 위젯으로 Sonarr, Radarr, Plex, Pi-hole 등의 상태를 실시간으로 확인할 수 있습니다. YAML 설정 파일 없이 브라우저에서 모든 것을 관리합니다.

항목	내용
공식 사이트	https://homarr.dev
GitHub	https://github.com/homarr-labs/homarr
라이선스	Apache License 2.0
GitHub Stars	6k+
Docker 이미지	`ghcr.io/homarr-labs/homarr:latest`
기본 포트	7575

왜 Homarr인가?

1. No YAML, No Code

설정 파일을 편집할 필요가 없습니다. 브라우저에서 클릭 몇 번으로 앱을 추가하고 위젯을 배치합니다.

2. 드래그앤드롭 그리드 시스템

마우스로 끌어다 놓기만 하면 됩니다. 위젯 크기 조절, 위치 변경, 카테고리 정리가 모두 시각적으로 가능합니다.

3. 11,000개 이상의 내장 아이콘

별도로 아이콘을 찾을 필요 없습니다. 대부분의 셀프호스팅 앱 아이콘이 내장되어 있습니다.

4. 내장 인증 시스템

OIDC, LDAP 연동은 물론 기본 사용자 인증도 지원합니다. 별도의 인증 프록시 없이도 안전하게 사용할 수 있습니다.

5. 멀티 보드 지원

여러 개의 대시보드를 만들어 용도별로 분리할 수 있습니다. 미디어용, 인프라용, 가족용 등.

6. 실시간 업데이트

WebSocket을 통해 위젯 데이터가 실시간으로 갱신됩니다.

Homarr vs 다른 대시보드

항목	Homarr	Homepage	Dashy
설정 방식	드래그앤드롭 UI	YAML 파일	YAML + UI
학습 곡선	⭐ 매우 낮음	⭐⭐⭐ 중간	⭐⭐⭐ 중간
내장 인증	✅ OIDC/LDAP	❌	⚠️ 제한적
내장 아이콘	11,000+	외부 참조	외부 참조
서비스 위젯	30개+	100개+	50개+
모바일 지원	✅	✅	✅
멀티 보드	✅	❌	✅
Git 버전 관리	⚠️ (DB 기반)	✅ (YAML)	✅ (YAML)
추천 대상	일반 사용자, 입문자	개발자, DevOps	고급 커스터마이징

Homarr 선택이 좋은 경우:

YAML 설정이 어렵거나 귀찮을 때
가족이나 비개발자도 사용해야 할 때
빠르게 대시보드를 만들고 싶을 때
내장 인증이 필요할 때

Docker Compose로 설치하기

기본 설치 (Homarr 1.0+)

services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Docker 통합 (선택)
      - ./homarr/appdata:/appdata
    environment:
      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string

SECRET_ENCRYPTION_KEY 생성

# 64자 HEX 문자열 생성
openssl rand -hex 32

설치 및 실행

# 디렉토리 생성
mkdir -p ~/homarr && cd ~/homarr

# SECRET_ENCRYPTION_KEY 생성
export SECRET_KEY=$(openssl rand -hex 32)
echo "SECRET_ENCRYPTION_KEY: $SECRET_KEY"

# docker-compose.yml 파일에 키 입력 후
docker compose up -d

# 로그 확인
docker logs -f homarr

브라우저에서 http://<서버IP>:7575로 접속합니다.

초기 설정

1. 관리자 계정 생성

첫 접속 시 관리자 계정을 생성합니다.

강력한 비밀번호 필수 (대소문자, 숫자, 특수문자)
이 계정은 삭제할 수 없으며 전체 권한을 가집니다

2. 첫 번째 보드 생성

“Create your first board” 버튼을 클릭하여 대시보드를 생성합니다.

3. 편집 모드 진입

오른쪽 상단의 연필 아이콘을 클릭하면 편집 모드로 전환됩니다.

앱 추가하기

기본 앱 (북마크)

편집 모드에서 “+” 버튼 클릭
“App” 선택
이름, URL, 아이콘 입력
그리드에 드래그하여 배치
“Save” 클릭

예시:
- 이름: Portainer
- URL: http://192.168.1.100:9000
- 아이콘: portainer (자동 검색)

아이콘 검색

아이콘 필드에 앱 이름을 입력하면 11,000개 이상의 내장 아이콘에서 자동 검색됩니다.

plex → Plex 아이콘
sonarr → Sonarr 아이콘
jellyfin → Jellyfin 아이콘

커스텀 이미지 URL도 사용 가능합니다.

위젯 추가하기

위젯은 서비스의 실시간 데이터를 표시합니다.

위젯 종류

카테고리	위젯
미디어	Plex, Jellyfin, Emby, Sonarr, Radarr, Lidarr
다운로드	qBittorrent, Transmission, Deluge, SABnzbd, NZBGet
DNS	Pi-hole, AdGuard Home
모니터링	Dash., Glances, Proxmox
요청	Overseerr, Jellyseerr, Ombi
기타	RSS 피드, 메모장, 날씨, 시계, 캘린더

위젯 추가 방법

편집 모드에서 “+” → “Widget” 선택
위젯 유형 선택 (예: Sonarr)
통합(Integration) 연결 필요

통합 (Integrations) 설정

위젯이 서비스 데이터를 가져오려면 통합 설정이 필요합니다.

통합 추가

좌측 메뉴 → “Manage” → “Integrations”
“Add Integration” 클릭
서비스 유형 선택 (예: Sonarr)
URL과 API 키 입력

Sonarr 통합 예시

유형: Sonarr
이름: My Sonarr
URL: http://192.168.1.100:8989
API Key: your-sonarr-api-key

API 키 찾기

서비스	API 키 위치
Sonarr/Radarr	Settings → General → API Key
Plex	계정 설정 → 인증된 기기
Jellyfin	Dashboard → API Keys
Pi-hole	Settings → API → Show API token
Proxmox	Datacenter → API Tokens

위젯에 통합 연결

위젯 편집
“Integration” 드롭다운에서 생성한 통합 선택
저장

주요 위젯 상세

미디어 캘린더

Sonarr/Radarr와 연동하여 예정된 TV 에피소드와 영화를 캘린더로 표시합니다.

위젯: Calendar
통합: Sonarr, Radarr (복수 선택 가능)
크기: 2x2 이상 권장

다운로드 클라이언트

qBittorrent, Transmission 등의 다운로드 현황을 실시간으로 표시합니다.

표시 정보:
- 다운로드/업로드 속도
- 진행 중인 토렌트 목록
- 완료된 항목

DNS Hole (Pi-hole/AdGuard)

표시 정보:
- 총 쿼리 수
- 차단된 쿼리 수
- 차단률 (%)
- 활성화/비활성화 토글

시스템 상태 (Dash.)

표시 정보:
- CPU 사용률
- 메모리 사용률
- 디스크 사용률
- 네트워크 트래픽

레이아웃 구성

동적 섹션 (Dynamic Section)

시각적으로 위젯을 그룹화하는 박스입니다.

“+” → “Dynamic Section”
섹션 크기 조절
위젯을 섹션 안으로 드래그

그리드 조정

위젯 모서리를 드래그하여 크기 조절
위젯을 드래그하여 위치 이동
겹치지 않도록 자동 정렬

Docker 통합

Docker 소켓을 마운트하면 컨테이너를 직접 관리할 수 있습니다.

활성화 조건

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

기능

실행 중인 컨테이너 목록 보기
컨테이너 시작/정지/재시작
컨테이너를 앱으로 자동 추가
컨테이너 상태 모니터링

컨테이너를 앱으로 추가

좌측 메뉴 → “Manage” → “Docker”
추가할 컨테이너 선택
“Add to Homarr” 클릭
URL 확인 후 추가

사용자 관리

사용자 추가

좌측 메뉴 → “Manage” → “Users”
“Add User” 클릭
사용자명, 비밀번호, 권한 설정

권한 시스템

권한	설명
Admin	모든 권한 (설정, 사용자 관리)
Editor	보드 편집 가능
Viewer	보기만 가능

OIDC/LDAP 연동

외부 인증 시스템과 연동할 수 있습니다.

지원:
- Authentik
- Authelia
- Keycloak
- Active Directory (LDAP)

멀티 보드

보드 추가

좌측 메뉴 → “Boards”
“Create Board” 클릭
보드 이름 입력

용도별 보드 예시

- 미디어 보드: Plex, Sonarr, Radarr, Overseerr
- 인프라 보드: Proxmox, Portainer, Pi-hole
- 가족 보드: 간단한 앱 링크만

기본 보드 설정

특정 보드를 로그인 시 기본으로 표시하도록 설정할 수 있습니다.

테마 및 커스터마이징

배경 이미지

보드 설정 열기
“Background” 섹션
이미지 URL 입력 또는 업로드

색상 테마

Light / Dark 모드
시스템 설정 따라가기
커스텀 색상 (CSS)

CSS 커스터마이징

고급 사용자는 CSS를 직접 수정할 수 있습니다.

/* 예: 카드 테두리 둥글게 */
.mantine-Card-root {
  border-radius: 16px !important;
}

검색 기능

글로벌 검색 (Ctrl+K)

앱 이름으로 검색
위젯 데이터 검색 (통합 서비스 내)
웹 검색 (Google, DuckDuckGo 등)

통합 검색

Sonarr, Radarr 등의 통합이 설정되어 있으면 해당 서비스 내 콘텐츠도 검색됩니다.

예: "Breaking Bad" 검색
→ Sonarr 라이브러리에서 결과 표시
→ 클릭하면 Sonarr 페이지로 이동

백업 및 복원

데이터 위치

모든 설정은 /appdata 볼륨에 저장됩니다.

# 백업
tar -czvf homarr-backup-$(date +%Y%m%d).tar.gz ./homarr/appdata

# 복원
tar -xzvf homarr-backup-20260120.tar.gz

보드 내보내기/가져오기

UI에서 개별 보드를 ZIP 파일로 내보내고 가져올 수 있습니다.

보드 설정 → “Export”
ZIP 파일 다운로드
다른 Homarr 인스턴스에서 “Import”

트러블슈팅

위젯이 데이터를 표시하지 않음

통합이 올바르게 설정되었는지 확인
API 키가 유효한지 확인
Homarr 컨테이너에서 서비스에 접근 가능한지 확인
컨테이너 로그 확인: docker logs homarr

Docker 컨테이너가 표시되지 않음

Docker 소켓이 마운트되었는지 확인
소켓 권한 확인
Homarr 컨테이너 재시작

통합 타임아웃

Pi-hole 등 일부 서비스는 타임아웃이 발생할 수 있습니다.

Homarr에서 DNS를 Pi-hole로 사용하지 않도록 설정
또는 IP 주소 직접 사용

마이그레이션 (0.x → 1.0)

Homarr 1.0은 완전히 새로 작성되어 볼륨 마운트가 변경되었습니다.

# 이전 버전
volumes:
  - ./homarr/configs:/app/data/configs
  - ./homarr/icons:/app/public/icons
  - ./homarr/data:/data

# 1.0 이상
volumes:
  - ./homarr/appdata:/appdata

공식 마이그레이션 가이드를 참조하세요.

고급 설정

리버스 프록시

Nginx Proxy Manager 또는 Traefik 뒤에 배치할 수 있습니다.

# Nginx 설정 예시
location / {
    proxy_pass http://homarr:7575;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

WebSocket 지원이 필요합니다 (실시간 업데이트용).

Kubernetes 배포

Helm 차트를 통한 Kubernetes 배포도 지원합니다.

helm repo add homarr https://homarr-labs.github.io/charts
helm install homarr homarr/homarr

마무리

Homarr는 홈 서버 대시보드의 진입 장벽을 크게 낮춘 프로젝트입니다. YAML 설정 없이 브라우저에서 드래그앤드롭으로 모든 것을 구성할 수 있어, 비개발자나 가족 구성원도 쉽게 사용할 수 있습니다.

내장 인증, 멀티 보드, 실시간 위젯 업데이트 등 실용적인 기능이 잘 갖춰져 있고, Sonarr/Radarr 캘린더 위젯은 미디어 서버 사용자에게 특히 유용합니다.

빠르게 대시보드를 만들고 싶거나, YAML 설정이 부담스럽다면 Homarr가 최적의 선택입니다.

개요