Homepage 대시보드의 가장 큰 장점 중 하나는 Docker와 연동하여 컨테이너의 상태를 실시간으로 보여주고, 각 서비스에 특화된 정보를 표시하는 위젯(Widget) 기능입니다.
이 가이드에서는 Docker로 실행 중인 Navidrome 뮤직 서버를 Homepage 대시보드에 추가하고, 현재 재생 중인 음악 정보를 표시하는 위젯을 설정하는 방법을 단계별로 안내합니다.
사전 확인#
먼저, Homepage와 Navidrome 컨테이너가 동일한 서버에서 정상적으로 실행 중인지 확인합니다. 터미널에서 아래 명령어를 실행합니다.
docker ps
아래와 같이 homepage와 navidrome 컨테이너가 모두 실행 중인 상태여야 합니다.
CONTAINER ID IMAGE COMMAND STATUS NAMES
b0f30d7fad7b ghcr.io/gethomepage/homepage:latest "docker-entrypoint.s…" Up 44 minutes homepage
fe66d8aab05e deluan/navidrome:latest "/app/navidrome" Up 3 weeks navidrome
...
Navidrome API 토큰 생성#
Homepage 위젯이 Navidrome 서버와 통신하려면 API 인증을 위한 토큰이 필요합니다. Navidrome은 md5(password + salt) 형식으로 생성된 토큰을 사용합니다.
터미널에서 아래 명령어를 실행하여 토큰을 생성합니다.
md5sum <<< "navidrome비밀번호+나만의솔트문자열"
내비드롬비밀번호는 실제 Navidrome 로그인 시 사용하는 비밀번호로 바꿔주십시오.나만의솔트문자열은 아무도 모르는 임의의 문자열(salt)로 바꿔주십시오.- 명령어 실행 후 출력되는
e3a0d1f...와 같은 결과가 토큰이며,나만의솔트문자열은 salt 값입니다. 이 두 가지 값은 다음 단계에서 필요하므로 잘 기록해 두어야 합니다.
Homepage 설정 수정#
Homepage의 설정은 config 디렉토리 내의 YAML 파일들을 통해 관리됩니다.
Docker 연동 설정 (docker.yaml)#
Homepage가 서버의 Docker 엔진과 통신할 수 있도록 설정합니다. config/docker.yaml 파일을 열고 아래와 같이 수정합니다.
# config/docker.yaml
# my-docker 라는 이름으로 Docker 소켓을 연결합니다.
my-docker:
socket: /var/run/docker.sock
외부 서버에 적용된 docker와 연동하려면 아래와 같이 설정합니다.
my-remote-docker:
host: 192.168.0.101
port: 2375
tls:
keyFile: tls/key.pem
caFile: tls/ca.pem
certFile: tls/cert.pem
docker의 외부 연동과 관련된 내용은 아래 글을 참고해주세요
이 설정을 통해 Homepage는 my-docker라는 이름으로 Docker 컨테이너들의 상태를 읽어올 수 있게 됩니다.
Navidrome 서비스 및 위젯 추가 (services.yaml)#
이제 실제 대시보드에 표시될 Navidrome 서비스를 추가합니다. config/services.yaml 파일을 열고 원하는 그룹에 아래 내용을 추가하십시오.
# config/services.yaml
- Media: # 서비스 그룹 이름
- Navidrome:
# 서비스 아이콘 (Material Design Icons에서 선택)
icon: navidrome.png
# 클릭 시 이동할 URL
href: https://navidrome.your-domain.com/
# 서비스에 대한 간단한 설명
description: Navidrome Music server
# 3.1에서 설정한 Docker 서버 이름
server: my-docker
# 상태를 확인할 Docker 컨테이너 이름
container: navidrome
# Navidrome 'Now Playing' 위젯 설정
widget:
type: navidrome
url: https://navidrome.your-domain.com
user: your_navidrome_username
# 2단계에서 생성한 토큰과 솔트 값
token: e3a0d1f...
salt: 나만의솔트문자열
server&container:my-docker서버의navidrome컨테이너 상태를 추적하여, 대시보드에 초록색 점(실행 중)으로 표시해 줍니다.widget:url: Navidrome 접속 주소를 입력합니다.user: Navidrome 사용자 이름을 입력합니다.token&salt: 2단계에서 생성하고 기록해 둔 토큰과 salt 값을 정확하게 입력합니다.
결과 확인#
docker.yaml과 services.yaml 파일 수정을 완료하고 저장하면, Homepage는 자동으로 설정을 다시 읽어옵니다. 별도의 재시작 없이 대시보드 웹페이지를 새로고침하면 변경사항이 적용됩니다.
위와 같이 “Media” 그룹에 Navidrome 서비스가 추가되고, 컨테이너가 정상 실행 중임을 나타내는 상태 아이콘과 함께 현재 재생 중인 음악 정보가 위젯에 표시되면 성공입니다.
마무리하며#
이것으로 Homepage 대시보드에 Docker 컨테이너 상태와 연동되는 동적 위젯을 추가하는 과정이 완료되었습니다. 이와 같은 방식으로 다른 여러 서비스(Sonarr, Radarr, Plex 등)도 Homepage에 통합하여, 나만의 강력한 통합 서버 관리 대시보드를 구축할 수 있습니다.
참조
- Homepage 공식 문서 - Navidrome Widget: https://gethomepage.dev/widgets/services/navidrome/
- Homepage 공식 문서 - Docker Integration: https://gethomepage.dev/configs/docker/#services