Deploying Navidrome Music Server

Introduction

Navidrome is a self-hosted music streaming server that lets you access your personal music collection from anywhere. Built with Go and React, Navidrome is fast, lightweight, and compatible with hundreds of Subsonic-compatible clients across all platforms. It’s like having your own Spotify, but with complete control over your music library.

Modern and actively developed, Navidrome focuses on performance and simplicity while supporting a rich ecosystem of mobile and desktop clients. Whether you have a modest collection or hundreds of thousands of tracks, Navidrome handles it efficiently with minimal resource usage.

Key highlights of Navidrome:

• Subsonic API Compatible: Works with hundreds of existing clients on iOS, Android, desktop, and web
• Modern Web Interface: Beautiful, responsive web player built with React
• Multi-User Support: Create accounts for family and friends with individual libraries and preferences
• Transcoding: On-the-fly audio transcoding for bandwidth optimization
• Scrobbling: Last.fm and ListenBrainz integration for play tracking
• Smart Playlists: Automatic playlists based on play history and preferences
• Metadata Support: Full support for album art, lyrics, and extensive tags
• Lightweight: Written in Go with minimal memory footprint
• Active Development: Regular updates with new features and improvements

This guide walks through deploying Navidrome on Klutch.sh using Docker.

Why Deploy Navidrome on Klutch.sh

Deploying Navidrome on Klutch.sh provides several advantages for music streaming:

Stream From Anywhere: Access your entire music collection from any device with an internet connection. No more syncing files between devices.

Always Available: Your music server runs 24/7 without managing home servers or dealing with dynamic IP addresses.

Simplified Deployment: Push your configuration to GitHub and Klutch.sh handles containerization. No complex server setup required.

Persistent Storage: Your music library, database, and user preferences persist across container restarts.

HTTPS by Default: Secure access to your music with automatic SSL certificates.

Custom Domain: Use your own domain for a personalized streaming experience.

Prerequisites

Before deploying Navidrome on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Your music library files ready to upload
• Basic familiarity with Docker concepts

Understanding Navidrome Architecture

Navidrome has a simple, efficient architecture:

Go Backend: Handles API requests, music scanning, transcoding, and user management.

React Frontend: Modern web player with responsive design.

SQLite Database: Stores metadata, playlists, play counts, and user data.

FFmpeg Integration: Powers on-the-fly transcoding for various audio formats and bitrates.

Subsonic API: Standard API compatibility enables use of existing mobile and desktop clients.

Preparing Your Repository

Create a GitHub repository for your Navidrome deployment.

Repository Structure

navidrome-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM deluan/navidrome:latest

# Environment configuration
ENV ND_SCANSCHEDULE=1h
ENV ND_LOGLEVEL=info
ENV ND_SESSIONTIMEOUT=24h
ENV ND_BASEURL=""

# Expose web interface
EXPOSE 4533

# Volumes for data and music
VOLUME ["/data", "/music"]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying Navidrome on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “navidrome” or “music”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Navidrome serves its web interface over HTTP:

• Select HTTP as the traffic type
• Set the internal port to 4533

Set Environment Variables

Configure the application:

Variable	Value
ND_SCANSCHEDULE	1h (library scan interval)
ND_LOGLEVEL	info
ND_SESSIONTIMEOUT	24h
ND_BASEURL	Leave empty or set if using subpath

Attach Persistent Volumes

Configure storage:

Mount Path	Recommended Size	Purpose
/data	5 GB	Database, cache, and transcoded files
/music	Based on collection	Your music library

Deploy Your Application

Click Deploy to build and start your Navidrome instance.

Access Navidrome

Visit https://your-app-name.klutch.sh to access the web interface.

Initial Configuration

First-Time Setup

On first access:

1. Create your admin account
2. Set a strong password
3. You’ll be logged in to the web interface

Library Scanning

Navidrome automatically scans for music:

1. Upload music to the /music volume
2. Wait for automatic scan or trigger manually
3. Music appears in your library

User Management

Create additional users:

1. Go to Settings > Users
2. Add new user accounts
3. Configure user permissions
4. Each user has their own playlists and preferences

Uploading Your Music

File Transfer Options

Get your music onto the persistent volume:

SFTP/SCP: If you have direct storage access, use secure file transfer.

Companion File Manager: Deploy a file manager alongside Navidrome for web-based uploads.

Cloud Sync: Use tools like rclone to sync from cloud storage.

Supported Formats

Navidrome supports many audio formats:

• MP3
• FLAC
• AAC/M4A
• OGG Vorbis
• Opus
• WMA
• ALAC
• WAV
• And more…

Organization Tips

Navidrome reads metadata, but good organization helps:

/music/
├── Artist Name/
│   ├── Album Name (Year)/
│   │   ├── 01 - Track Name.flac
│   │   ├── 02 - Track Name.flac
│   │   └── cover.jpg
│   └── Another Album/
└── Various Artists/
    └── Compilation Album/

Using Mobile Clients

Subsonic-Compatible Clients

Navidrome works with many clients:

iOS:

• play:Sub
• SubStreamer
• Amperfy

Android:

• Symfonium
• Ultrasonic
• DSub
• Subtracks

Desktop:

• Sublime Music
• Sonixd
• Supersonic

Client Configuration

Configure clients with:

• Server URL: https://your-app-name.klutch.sh
• Username: Your Navidrome username
• Password: Your Navidrome password

Web Interface Features

Now Playing

The web player includes:

• Album art display
• Playback controls
• Queue management
• Volume control
• Shuffle and repeat

Library Browsing

Navigate your collection:

• Artists view
• Albums view
• Songs list
• Genres
• Decades
• Recently played
• Recently added

Playlists

Organize your music:

1. Create custom playlists
2. Add songs via context menu
3. Reorder tracks
4. Smart playlists based on criteria

Search

Find music quickly:

• Full-text search
• Search by artist, album, or song
• Instant results

Transcoding

Automatic Transcoding

Navidrome can transcode on-the-fly:

• Reduces bandwidth for streaming
• Compatible with all clients
• Preserves original files

Configuration

Set transcoding options:

ND_TRANSCODINGCACHESIZE=150MB
ND_IMAGINARTCACHESIZE=50MB

Client Settings

Clients can request specific quality:

• Raw (original quality)
• Various MP3 bitrates
• Opus for efficiency

Scrobbling

Last.fm Integration

Track your listening:

1. Go to Settings
2. Connect Last.fm account
3. Plays automatically scrobble

ListenBrainz

Alternative scrobbling:

1. Get ListenBrainz token
2. Configure in settings
3. Track plays on open platform

Multi-User Features

User Accounts

Each user gets:

• Personal playlists
• Individual play counts
• Separate scrobbling
• Custom preferences

Sharing

Share music with users:

• Public playlists
• Shared libraries
• Guest accounts

Production Best Practices

Performance

• Allocate sufficient resources for library size
• Enable caching for faster responses
• Configure appropriate scan intervals

Backup

Protect your configuration:

1. Backup /data directory regularly
2. Export playlists
3. Keep music files backed up separately

Security

• Use strong passwords
• Keep Navidrome updated
• HTTPS is automatic on Klutch.sh

Troubleshooting

Music Not Appearing

• Check files are in supported formats
• Verify file permissions
• Check metadata tags
• Trigger manual scan from web UI

Playback Issues

• Verify client configuration
• Check transcoding settings
• Review browser console for errors
• Test with web player

Slow Library Scan

• Large libraries take time initially
• Subsequent scans are faster
• Adjust scan schedule if needed

Client Connection Failed

• Verify server URL (include https://)
• Check username/password
• Ensure app supports Subsonic API

Additional Resources

• Official Navidrome Website
• Navidrome Documentation
• Navidrome GitHub Repository
• Compatible Apps List
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Navidrome on Klutch.sh gives you a personal music streaming service that rivals commercial offerings. With support for hundreds of clients, automatic transcoding, and multi-user capabilities, Navidrome provides everything needed for a complete music streaming experience.

Whether you’re streaming your carefully curated FLAC collection or sharing music with family, Navidrome on Klutch.sh provides reliable, always-available access to your personal music library.