안녕하세요! 🎵 여러분은 좋아하는 음악을 어떻게 듣고 계신가요? Spotify, Apple Music 같은 스트리밍 서비스도 좋지만, 내가 직접 관리하는 음악 컬렉션을 언제 어디서든 나만의 방식으로 듣고 싶다는 생각을 해보신 적은 없으신가요? 오늘은 바로 그 꿈을 현실로 만들어 줄 Navidrome이라는 멋진 오픈소스 음악 스트리밍 서버를 Docker Compose를 이용해 쉽고 빠르게 구축하는 방법을 자세히 알려드리겠습니다. 🐳🚀
🌟 1. Navidrome이란 무엇인가요? 왜 사용해야 할까요?
Navidrome은 가볍고 빠르며, 현대적인 웹 인터페이스를 갖춘 개인용 음악 스트리밍 서버입니다. 서브소닉(Subsonic) API를 지원하여 다양한 서드파티 클라이언트 앱과 호환됩니다.
Navidrome을 사용해야 하는 이유:
- 나만의 음악 컬렉션 관리: 스트리밍 서비스에 없는 희귀한 곡이나 고음질 음원을 직접 관리하고 싶을 때 최적입니다.
- 완벽한 제어: 내 서버에 음악이 있으니 데이터 주권은 온전히 나에게 있습니다.
- 깔끔하고 직관적인 UI: 웹 인터페이스가 매우 현대적이고 사용자 친화적입니다.
- 다양한 기기 지원: 웹 브라우저는 물론, Subsonic API를 지원하는 모바일 앱(Symfonium, Dsub 등)을 통해 스마트폰, 태블릿에서도 편리하게 음악을 들을 수 있습니다.
- 가볍고 효율적: 리소스 사용량이 적어 저사양 기기(라즈베리 파이 등)에서도 잘 작동합니다.
- 오픈소스: 투명하고 활발한 커뮤니티 지원을 받을 수 있습니다.
🐳 2. Docker Compose를 왜 사용하나요?
Docker Compose는 여러 Docker 컨테이너를 정의하고 실행하는 도구입니다. 복잡한 애플리케이션 환경을 하나의 YAML 파일로 정의하여 쉽게 배포하고 관리할 수 있게 해줍니다.
Docker Compose의 장점:
- 간편한 배포: 몇 줄의 코드로 복잡한 환경을 구축할 수 있습니다.
- 환경 일관성: 개발, 테스트, 운영 환경 간의 차이를 줄여줍니다.
- 쉬운 관리: 컨테이너 시작, 중지, 재시작, 삭제 등이 명령어 하나로 가능합니다.
- 독립적인 환경: 각 서비스가 격리된 환경에서 실행되어 충돌을 방지합니다.
🛠️ 3. 시작하기 전 준비물
Navidrome을 설치하기 전에 다음 사항들을 준비해주세요.
- Docker 및 Docker Compose 설치: 서버에 Docker와 Docker Compose가 설치되어 있어야 합니다. 설치 방법은 각 운영체제에 따라 다르니 공식 문서를 참고해주세요.
- 음악 파일 준비: 스트리밍하고 싶은 음악 파일들 (MP3, FLAC 등)이 준비되어 있어야 합니다. 이 파일들을 서버의 특정 폴더에 넣어둘 것입니다.
📂 4. 프로젝트 구조 설계
Navidrome과 Docker Compose 파일을 위한 깔끔한 디렉토리 구조를 만듭니다.
navidrome/
├── docker-compose.yml
├── data/
└── music/navidrome/: 모든 파일을 담을 최상위 디렉토리입니다.docker-compose.yml: Docker Compose 설정 파일입니다.data/: Navidrome의 설정, 데이터베이스, 캐시 등이 저장될 폴더입니다. (이 폴더가 영구적으로 보존되어야 합니다!)music/: 여러분의 음악 파일들이 저장될 폴더입니다. 여기에 모든 음악 파일을 넣어주세요! 💿
📝 5. docker-compose.yml 파일 작성
이제 navidrome 디렉토리 안에 docker-compose.yml 파일을 만들고 다음 내용을 입력합니다.
version: '3.8'
services:
navidrome:
image: deluan/navidrome:latest
container_name: navidrome
restart: unless-stopped
ports:
- "4533:4533" # 호스트 포트:컨테이너 포트
volumes:
- ./data:/data
- ./music:/music:ro # 음악 파일이 있는 폴더 (읽기 전용)
environment:
# Navidrome 환경 변수 설정
# https://www.navidrome.org/docs/usage/configuration-options/
- ND_SCANINTERVAL=1h # 음악 스캔 주기 (1시간마다)
- ND_LOGLEVEL=info # 로그 레벨 (info, debug, warn, error)
- ND_MUSICFOLDER=/music # 컨테이너 내부의 음악 폴더 경로 (매우 중요!)
- TZ=Asia/Seoul # 시간대 설정 (필요에 따라 변경)
# ND_LASTFM_API_KEY: "YOUR_LASTFM_API_KEY" # Last.fm 연동 (선택 사항)
# ND_LASTFM_SHARED_SECRET: "YOUR_LASTFM_SHARED_SECRET" # Last.fm 연동 (선택 사항)
# ND_SPOTIFY_CLIENT_ID: "YOUR_SPOTIFY_CLIENT_ID" # Spotify 연동 (선택 사항)
# ND_SPOTIFY_CLIENT_SECRET: "YOUR_SPOTIFY_CLIENT_SECRET" # Spotify 연동 (선택 사항)
# CPU 및 메모리 제한 (선택 사항, 리소스가 제한된 환경에서 유용)
# deploy:
# resources:
# limits:
# cpus: '0.5' # 0.5 CPU 코어
# memory: 512M # 512MB 메모리docker-compose.yml 파일 설명:
version: '3.8': Docker Compose 파일의 버전을 지정합니다. 최신 버전을 사용하는 것이 좋습니다.services:: 실행할 서비스들을 정의합니다. 여기서는navidrome이라는 하나의 서비스만 있습니다.image: deluan/navidrome:latest: Navidrome의 공식 Docker 이미지를 사용합니다.latest태그는 항상 최신 버전을 가져옵니다.container_name: navidrome: 컨테이너의 이름을navidrome으로 지정하여 나중에 식별하기 쉽게 합니다.restart: unless-stopped: 컨테이너가 예기치 않게 종료되거나, Docker 데몬이 재시작될 때 자동으로 다시 시작되도록 설정합니다.ports: - "4533:4533": 포트 매핑 설정입니다.- 왼쪽
4533은 호스트(서버)의 포트입니다. 이 포트로 Navidrome에 접속하게 됩니다. - 오른쪽
4533은 컨테이너 내부의 포트입니다. Navidrome은 기본적으로 4533번 포트를 사용합니다. - 만약 호스트의 4533번 포트가 이미 사용 중이라면, 왼쪽 포트 번호를
8080:4533처럼 다른 번호로 변경할 수 있습니다.
- 왼쪽
volumes:: 데이터를 영구적으로 저장하고, 호스트의 파일에 접근하기 위해 사용합니다.- ./data:/data: 호스트의 현재 디렉토리(navidrome디렉토리) 아래data폴더를 컨테이너 내부의/data폴더에 마운트합니다. Navidrome의 설정, 데이터베이스, 캐시 등이 이data폴더에 저장됩니다. 이 폴더를 백업하면 Navidrome의 모든 설정과 메타데이터를 백업하는 것입니다.- ./music:/music:ro: 호스트의 현재 디렉토리 아래music폴더를 컨테이너 내부의/music폴더에 마운트합니다.ro는 “read-only”를 의미하며, 컨테이너가 이 폴더의 내용을 읽기만 할 수 있도록 하여 데이터 손상을 방지합니다. 여러분의 음악 파일들을 이music폴더 안에 넣어두세요.
environment:: Navidrome 애플리케이션의 동작을 제어하는 환경 변수들입니다.ND_SCANINTERVAL=1h: Navidrome이 새로운 음악 파일을 스캔하는 주기를 1시간으로 설정합니다.1m(1분),1d(1일),(자동 스캔 비활성화) 등으로 변경할 수 있습니다.ND_LOGLEVEL=info: Navidrome의 로그 레벨을 설정합니다. 디버깅 시에는debug로 변경할 수 있습니다.ND_MUSICFOLDER=/music: 매우 중요한 설정입니다! Navidrome에게 음악 파일이 컨테이너 내부의 어디에 있는지 알려줍니다. 위의volumes설정에서:/music으로 마운트했으므로, 이 값은/music이어야 합니다.TZ=Asia/Seoul: 컨테이너의 시간대를 설정합니다. 로그 시간이나 음악 파일 생성 시간 등을 정확하게 표시하는 데 도움이 됩니다.- Last.fm, Spotify 연동 등 추가적인 설정은 공식 문서를 참고하여 주석을 해제하고 사용하시면 됩니다.
🚀 6. Navidrome 실행하기
docker-compose.yml 파일 작성을 완료했다면, 이제 Navidrome을 실행할 준비가 되었습니다!
-
음악 파일 배치:
navidrome/music/디렉토리 안에 여러분의 모든 음악 파일들을 넣어주세요. 폴더별로 정리해두면 Navidrome에서도 깔끔하게 표시됩니다. 🎶# 예시: # navidrome/music/ # ├── Band_A/ # │ ├── Album_1/ # │ │ ├── 01_Song_A.mp3 # │ │ └── 02_Song_B.flac # │ └── Album_2/ # │ └── 01_Song_C.mp3 # └── Band_B/ # └── Single_D.mp3 -
컨테이너 실행: 터미널을 열고
navidrome디렉토리로 이동한 다음, 다음 명령어를 실행합니다.cd navidrome docker compose up -ddocker compose up:docker-compose.yml파일에 정의된 서비스들을 시작합니다.-d(detached mode): 컨테이너를 백그라운드에서 실행하여 터미널을 계속 사용할 수 있게 합니다.
-
실행 확인: 컨테이너가 정상적으로 실행되고 있는지 확인합니다.
docker compose psnavidrome컨테이너의 상태가Up으로 표시되면 성공입니다! ✅NAME IMAGE COMMAND SERVICE PORTS navidrome deluan/navidrome:latest "/app/navidrome --da…" navidrome 0.0.0.0:4533->4533/tcp
🌐 7. Navidrome 접속 및 초기 설정
이제 웹 브라우저를 열고 다음 주소로 접속합니다.
http://[당신의_서버_IP_주소]:4533
예시: http://localhost:4533 (로컬에서 실행했다면) 또는 http://192.168.1.100:4533 (서버 IP 주소)
-
관리자 계정 생성: Navidrome에 처음 접속하면 관리자 계정을 생성하는 화면이 나타납니다. 사용자 이름과 비밀번호를 입력하고 계정을 생성해주세요. 🛡️
-
음악 스캔: 계정을 생성하고 로그인하면 Navidrome이 자동으로
music폴더에 있는 음악 파일들을 스캔하여 라이브러리를 구축하기 시작합니다. 파일 수에 따라 시간이 다소 걸릴 수 있습니다. 진행 상황은 우측 상단의 아이콘을 통해 확인할 수 있습니다.스캔이 완료되면 멋진 음악 라이브러리가 눈앞에 펼쳐질 것입니다! ✨
📱 8. 모바일 클라이언트 앱 활용
Navidrome은 웹 인터페이스도 훌륭하지만, 모바일 기기에서는 Subsonic API를 지원하는 다양한 앱들을 활용하면 더욱 편리하게 음악을 즐길 수 있습니다.
몇 가지 인기 있는 앱 추천:
- Android: Symfonium (강력 추천! 👍), Dsub, Subtracks
- iOS: play:Sub, iSub, Substreamer
앱 설정 시, 서버 주소는 http://[당신의_서버_IP_주소]:4533을 입력하고, 생성한 관리자 계정으로 로그인하시면 됩니다. (외부에서 접속하려면 포트 포워딩이나 리버스 프록시 설정이 필요할 수 있습니다.)
💡 9. 고급 설정 및 팁
-
음악 재스캔: 새 음악 파일을 추가했는데 바로 보이지 않는다면, Navidrome 웹 UI에서 “설정(Settings)” -> “스캔(Scan Library)”으로 이동하여 수동으로 라이브러리를 재스캔할 수 있습니다.
-
업데이트: Navidrome을 최신 버전으로 업데이트하려면 다음 명령어를 사용하세요.
cd navidrome docker compose pull navidrome # 최신 이미지 다운로드 docker compose up -d # 새 이미지로 컨테이너 재시작 -
백업:
navidrome/data폴더만 백업하면 Navidrome의 모든 설정, 데이터베이스, 스캔된 메타데이터를 보존할 수 있습니다. 다른 서버로 이전하거나 복구할 때 이 폴더를 그대로 사용하면 됩니다. -
리버스 프록시 (Nginx/Caddy): 만약
http://yourdomain.com과 같은 도메인으로 접속하거나 HTTPS(SSL)를 적용하고 싶다면, Nginx나 Caddy와 같은 리버스 프록시를 앞에 두는 것을 강력히 추천합니다. 이를 통해 보안을 강화하고 포트 번호 없이 깔끔한 URL로 접속할 수 있습니다. (이 부분은 다음 기회에 더 자세히 다루겠습니다. 📚)
⚠️ 10. 문제 해결 (Troubleshooting)
- 컨테이너가 실행되지 않아요!
docker compose logs navidrome명령어로 로그를 확인하여 어떤 오류가 발생했는지 파악합니다.- 포트 충돌일 수 있습니다.
docker-compose.yml파일에서ports의 왼쪽 번호(4533:4533에서 왼쪽4533)를 다른 번호로 변경해보세요.
- 음악 파일이 보이지 않아요!
navidrome/music폴더에 음악 파일이 제대로 들어있는지 확인합니다.docker-compose.yml의ND_MUSICFOLDER경로가volumes설정과 일치하는지 (/music으로 설정되어 있는지) 다시 확인합니다.- 권한 문제일 수 있습니다.
music폴더에 Docker 컨테이너가 접근할 수 있는 읽기 권한이 있는지 확인합니다. (chmod -R 755 navidrome/music등으로 시도해볼 수 있지만,ro볼륨이라면 일반적으로 큰 문제 없습니다.)
- 접속이 안 돼요!
- 서버의 방화벽 설정(ufw, firewalld 등)에서 4533번 포트가 열려 있는지 확인합니다.
docker compose ps로 컨테이너가Up상태인지 다시 확인합니다.
🥳 11. 마무리하며
이제 여러분은 나만의 강력하고 멋진 음악 스트리밍 서버, Navidrome을 성공적으로 구축하셨습니다! 🎉 더 이상 스트리밍 서비스에 의존하지 않고, 직접 소유한 음악 컬렉션을 원하는 대로 즐길 수 있게 되었습니다. Docker Compose 덕분에 이 모든 과정이 훨씬 더 간편해졌다는 것을 느끼셨을 겁니다.
궁금한 점이나 문제가 발생하면 언제든지 댓글로 질문해주세요! 행복한 음악 생활 되세요! 🎶🎧✨