Getting Started

Getting Started

This page takes you from nothing to your first playlist.

What you need

• A running Navidrome server and a user account on it.
• Docker, or Node.js 20 if you want to run from source.
• Optional: a ListenBrainz token or a Last.fm API key. You can build playlists without them, but Popularity and some features need one. See Integrations.

1. Run naviList

The easiest way is Docker. Save this as docker-compose.yml and adjust the paths:

services:
  navilist:
    image: ghcr.io/ofernander/navilist:latest
    container_name: navilist
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./nsp:/nsp                # only needed for Navidrome Smart Playlists
    environment:
      - PORT=3000
      - LOG_LEVEL=info
      - TZ=Europe/Stockholm       # set this to your timezone

Then start it:

docker compose up -d

Set TZ. Scheduled playlist refreshes run on the container's clock, which is UTC unless you set a timezone. Without it, "daily at 06:00" means 06:00 UTC. See Auto-Refresh.

Your database and settings live in ./data. Back that folder up.

Running from source instead:

git clone https://github.com/ofernander/navilist.git
cd navilist
npm install
npm start

2. Connect Navidrome

1. Open http://localhost:3000. You land on the Playlists page.
2. Go to Settings and fill in the Navidrome URL, username and password.
3. Click Test Connection.
4. If your Navidrome has more than one music folder, click Load Folders and pick the ones naviList should use.
5. Click Save Settings.

You can also set these with environment variables. See Settings.

3. Sync your library

Go to Services and click Sync Library under Navidrome. This copies your library's track list into naviList's own database. Rules playlists are built from that copy, so nothing else works until it finishes.

After it finishes, naviList starts some background work: looking up MusicBrainz artist IDs, marking live recordings, and rating track popularity. This can take a while on a big library. See Background Jobs. You don't have to wait for it before building playlists.

After the first sync, naviList keeps itself current. It checks Navidrome for changes every 5 minutes, does a full library sync every 6 hours, and syncs external services every 30 minutes.

4. Optional services

In Settings, add whichever of these you use, then run Sync All for each one on the Services page:

• Last.fm: API key and username
• ListenBrainz: token and username
• Maloja: URL and API key
• Lidarr: URL, API key and the profile details

See Integrations for what each one adds.

5. Make your first playlist

1. On the Playlists page, click + New Playlist.
2. Choose naviList (Rules-based playlist) and click Continue.
3. Give it a name, pick a starting rule such as Artist or Genre, and fill in the value.
4. Click Preview. You'll see the tracks it would use. Click the ✕ next to any you don't want.
5. Click Save Playlist. It appears in Navidrome.

The Rules Builder page explains everything you can do from there.