Navidrome Deployment and Usage Guide

1. Prerequisites

System Requirements:

A machine running Linux, macOS, Windows, or a supported container platform
Go 1.21+ (only required if building from source)
For Docker deployments: Docker or Docker Compose

Music Library:

A collection of music files in formats like MP3, FLAC, OGG, Opus, AAC, M4A, WMA, WAV
Properly organized directory structure (Navidrome scans and indexes your files)

Optional but Recommended:

A reverse proxy (like Nginx, Caddy, or Traefik) for SSL/TLS termination
Domain name for external access (if exposing to the internet)

2. Installation

Docker (Recommended)

# Create directories for data and music
mkdir -p /path/to/navidrome/data
mkdir -p /path/to/your/music

# Run Navidrome with Docker
docker run -d \
  --name navidrome \
  --restart=unless-stopped \
  -p 4533:4533 \
  -v /path/to/navidrome/data:/data \
  -v /path/to/your/music:/music:ro \
  -e ND_SCANSCHEDULE=1h \
  -e ND_LOGLEVEL=info \
  deluan/navidrome:latest

Docker Compose

Create a docker-compose.yml file:

version: "3"
services:
  navidrome:
    image: deluan/navidrome:latest
    container_name: navidrome
    restart: unless-stopped
    ports:
      - "4533:4533"
    volumes:
      - "/path/to/navidrome/data:/data"
      - "/path/to/your/music:/music:ro"
    environment:
      ND_SCANSCHEDULE: 1h
      ND_LOGLEVEL: info

Pre-built Binaries

Download the appropriate binary for your platform from the releases page:

# Example for Linux x86_64
wget https://github.com/navidrome/navidrome/releases/download/v0.52.0/navidrome_0.52.0_Linux_x86_64.tar.gz
tar xzf navidrome_0.52.0_Linux_x86_64.tar.gz
sudo mv navidrome /usr/local/bin/

Build from Source

# Clone the repository
git clone https://github.com/navidrome/navidrome.git
cd navidrome

# Build the binary
make build

# The binary will be available at ./navidrome

3. Configuration

Configuration File

Navidrome looks for configuration in this order:

Command line flags
Environment variables (prefixed with ND_)
Configuration file (default: navidrome.toml in the same directory as the binary)

Create a configuration file at ~/.config/navidrome/navidrome.toml or /etc/navidrome/navidrome.toml:

# Server configuration
Address = "0.0.0.0"
Port = 4533
LogLevel = "info"
BaseURL = ""

# Music library
MusicFolder = "/path/to/your/music"
DataFolder = "/path/to/navidrome/data"

# Database
DbPath = "navidrome.db"

# Features
EnableTranscodingConfig = true
EnableDownloads = true
EnableExternalServices = true
EnableMediaFileCoverArt = true

# Transcoding
TranscodingCacheSize = "100MB"
DefaultDownsamplingFormat = "mp3"

# UI
UILoginBackgroundURL = ""
UIWelcomeMessage = "Welcome to Navidrome!"
MaxSidebarPlaylists = 100

Environment Variables

All configuration options can be set via environment variables by prefixing with ND_:

ND_MUSICFOLDER=/path/to/your/music
ND_DATAFOLDER=/path/to/navidrome/data
ND_PORT=4533
ND_LOGLEVEL=debug
ND_SCANSCHEDULE=1h

Important Configuration Options

MusicFolder: Path to your music library (required)
DataFolder: Where Navidrome stores its database, cache, and other data
ScanSchedule: Cron expression for automatic library scans (e.g., @every 1h)
BaseURL: Set this if running behind a reverse proxy (e.g., /music)

4. Build & Run

Development Build

# Clone and setup
git clone https://github.com/navidrome/navidrome.git
cd navidrome

# Install dependencies and build
make setup
make build

# Run with hot reload for development
make run

Production Build

# Build optimized binary
make build

# Create a systemd service file
sudo nano /etc/systemd/system/navidrome.service

Example systemd service file:

[Unit]
Description=Navidrome Music Server
After=network.target

[Service]
User=navidrome
Group=navidrome
Type=simple
ExecStart=/usr/local/bin/navidrome
WorkingDirectory=/var/lib/navidrome
Environment="ND_MUSICFOLDER=/path/to/your/music"
Environment="ND_DATAFOLDER=/var/lib/navidrome"
Restart=on-failure

[Install]
WantedBy=multi-user.target

Start the service:

sudo systemctl daemon-reload
sudo systemctl enable navidrome
sudo systemctl start navidrome

Plugin Development

Navidrome supports plugins through the Navidrome Plugin Development Kit (PDK):

# Generate PDK code from annotated interfaces
cd plugins/cmd/ndpgen
go run main.go -host-wrappers -input=./plugins/host -package=host

# Generate client wrappers
go run main.go -host-only -input=./plugins/host -output=./plugins/pdk

5. Deployment

Cloud Hosting (Managed)

PikaPods offers officially supported cloud hosting with one-click deployment. This is the simplest option for users who don't want to manage infrastructure.

Self-Hosted Options

Docker on VPS (Recommended)

# Use Docker Compose for easy management
docker-compose up -d

# Set up a reverse proxy with Nginx
sudo apt install nginx
sudo nano /etc/nginx/sites-available/navidrome

Example Nginx configuration:

server {
    listen 80;
    server_name music.yourdomain.com;

    location / {
        proxy_pass http://localhost:4533;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: navidrome
spec:
  replicas: 1
  selector:
    matchLabels:
      app: navidrome
  template:
    metadata:
      labels:
        app: navidrome
    spec:
      containers:
      - name: navidrome
        image: deluan/navidrome:latest
        ports:
        - containerPort: 4533
        volumeMounts:
        - name: music
          mountPath: /music:ro
        - name: data
          mountPath: /data
        env:
        - name: ND_LOGLEVEL
          value: "info"

Raspberry Pi

# Use ARM-compatible Docker image
docker run -d \
  --name navidrome \
  -p 4533:4533 \
  -v /mnt/music:/music:ro \
  -v /home/pi/navidrome/data:/data \
  deluan/navidrome:latest

6. Troubleshooting

Common Issues

1. Library not scanning

# Check logs
docker logs navidrome
# or
journalctl -u navidrome -f

# Ensure music folder permissions are correct
sudo chmod -R 755 /path/to/your/music

2. "Permission denied" errors

# For Docker, ensure proper volume permissions
docker run ... -v /path/to/music:/music:ro -v /path/to/data:/data

# Check UID/GID mapping
docker exec navidrome ls -la /music

3. High CPU/Memory usage

Reduce ScanSchedule frequency
Disable EnableArtworkPrecache if not needed
Adjust TranscodingCacheSize and ImageCacheSize

4. Subsonic clients not connecting

Ensure BaseURL is correctly set if behind reverse proxy
Check that port 4533 is open in firewall
Verify username/password (default: admin/admin)

5. Transcoding not working

# Enable transcoding in config
EnableTranscodingConfig = true

# Install ffmpeg
sudo apt install ffmpeg
# or
brew install ffmpeg

6. Database issues

# Backup database
cp /path/to/navidrome/data/navidrome.db /path/to/backup/

# Reset database (will rescan library)
rm /path/to/navidrome/data/navidrome.db
systemctl restart navidrome

7. Getting help

Check logs: ND_LOGLEVEL=debug provides detailed information
Visit the GitHub Issues
Join the Discord server
Check the Subreddit

Log Analysis

# Common log patterns and solutions:

# "Error opening music folder"
# Solution: Check MusicFolder path and permissions

# "Error scanning file"
# Solution: Check file permissions and format support

# "Transcoding failed"
# Solution: Install ffmpeg and check codec support

# "Database locked"
# Solution: Ensure only one instance is running

How to Deploy & Use navidrome