Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

Migrating from Navidrome

Navidrome is fantastic, incredible software, and I owe a huge amount for bringing self-hosting music into the modern age. However, there were a lot of neat things I wanted to try out and experiment with which required tighter integration between client and server. In order take full advantage of these things (see the features page), there are a variety of OpenSubsonic extensions that are specific to kōan (but by no means closed off to other clients), which are available by running kōan as your server.

A kōan server does the job Navidrome does: it indexes a music folder, serves it over the Subsonic API with OpenSubsonic extensions, and gives each person an account. Subsonic apps that work with Navidrome work with kōan.

You do not have to switch to use kōan's apps. The macOS, iOS, Android and Apple TV apps and the terminal UI play from a Navidrome server as they do from a kōan one, so a move can be gradual: run kōan beside Navidrome on the same read-only music folder, try it, and move clients one at a time.

What you gain

What you give up

These Navidrome features have no kōan equivalent today:

Translating a Navidrome setup

The container

A typical Navidrome compose file:

services:
  navidrome:
    image: deluan/navidrome:latest
    ports: ["4533:4533"]
    environment:
      ND_SCANSCHEDULE: 1h
      ND_ENABLESHARING: "true"
    volumes:
      - ./data:/data
      - /mnt/music:/music:ro

The kōan equivalent:

services:
  koan:
    image: ghcr.io/radiosilence/koan:latest
    ports: ["4000:4000"]
    environment:
      KOAN_LIBRARY__FOLDERS: '["/music"]'
      KOAN_GRAPHQL__ALLOWED_HOSTS: '["music.example.com"]'
      KOAN_SERVER__URL: https://music.example.com
      KOAN_SUBSONIC__ENABLED: "true"
    volumes:
      - koan-config:/config
      - /mnt/music:/music:ro

with koan-config declared under volumes:. As in Navidrome, the first visit to the web UI makes the admin: until an account exists it shows a setup page instead of sign-in. To keep that window shut, set KOAN_GRAPHQL__SETUP_WIZARD: "false" and create the admin from a shell in the container (see The first account):

docker compose exec koan koan auth setup

Docker Compose has a complete file with Caddy in front for TLS.

Navidrome kōan
/data /config: config, database, signing keys and the cover cache. The image runs as uid 1000, so a bind mount must be writable by it
ND_MUSICFOLDER KOAN_LIBRARY__FOLDERS, a list; several folders form one library
ND_SCANSCHEDULE, ND_SCANNER_WATCHERWAIT Nothing to set. The server scans at start and watches the folders for changes
ND_ENABLESHARING Always on; server.url sets the address links are built on
ND_BASEURL Not supported; give kōan its own hostname
ND_REVERSEPROXYUSERHEADER, ND_REVERSEPROXYWHITELIST KOAN_GRAPHQL__PROXY_AUTH_HEADER, KOAN_GRAPHQL__PROXY_AUTH_FROM, for the web UI; see Behind an authenticating proxy
Port 4533 Port 4000, which serves the web UI, the Subsonic API (/rest), GraphQL and MCP

kōan only reads the music folder, as Navidrome does. Both can mount the same folder at once while you try kōan out.

The reverse proxy

Point the proxy at port 4000 instead of 4533, and list the hostname in allowed_hosts: kōan refuses requests for any Host it was not given. The linked apps hold a WebSocket open at /rest/koanLink, so the proxy must pass WebSocket upgrades. Caddy does this by default:

music.example.com {
    reverse_proxy koan:4000
}

Accounts

Navidrome's accounts do not carry over. With the admin account made, create the rest on the web UI's Users page, or from the shell:

koan auth create-user --username alice --role user
koan auth invite alice --server https://music.example.com

The invite is a link that signs kōan's apps in directly and shows the details for any other Subsonic app. The web UI's Users page does the same. Roles are admin, user and readonly; Navidrome's admin and regular users map to the first two.

Subsonic clients

Change the server URL and sign in with the kōan account. kōan accepts every way Subsonic clients sign in:

Make API keys and app passwords on the web UI's Account page, one per client; kōan's Mac, iOS and Android apps make and revoke both under Settings → Account too. A client that reports error 41 is using token auth with the account's own password, which kōan cannot check because it keeps only a hash: give it an app password instead. See Authentication.

Favourites, play counts and playlists

There is no importer for Navidrome's database yet; #651 tracks one. Until then, favourites, ratings, play counts and the playlists made in Navidrome stay there and start empty in kōan.

Covers kept as image files beside the tracks carry over. kōan looks for cover.*, folder.* and front.* (JPEG, PNG or WebP, any case) in that order, then for art embedded in the files, which is Navidrome's default CoverArtPriority. A different CoverArtPriority is not read; kōan always uses this order.

Playlists kept as files in the music folder carry over: kōan reads Navidrome's smart playlists (.nsp) and .m3u/.m3u8 files when it scans. See Smart playlists.

Running both

To keep Navidrome running while moving across:

  1. Run kōan beside it on the same read-only music mount, on its own hostname.
  2. Sign kōan's apps in to the kōan server, and leave other clients on Navidrome.
  3. Move the remaining clients once kōan covers what they use, then stop Navidrome.

kōan's apps can stay pointed at Navidrome throughout. They sync its library, favourites and playlists, so nothing about them has to change until the server does.