Running a server
koan --headless runs kōan with no terminal UI, serving the library to other machines: a web UI, the Subsonic API, GraphQL and MCP, all on one port. The container image runs the same thing; see In a container.
Quick start
koan auth setup # signing keys and the first admin account
koan subsonic setup # turn on the Subsonic API
export KOAN_SERVER__URL=https://music.example.com
koan --headless --bind 0.0.0.0 # serve on every interface, port 4000The server refuses to start without server.url, the one address clients reach it at. It cannot tell which of the addresses it answers on another device can reach, and every link it hands out is built on this one: invites, share links, MCP's sign-in, the Last.fm callback. A server used only at home can give its LAN address, such as http://192.168.1.20:4000. Signed-in apps learn it from the server and know the server by it, so a phone that reaches it by its domain and a laptop that reaches it by its LAN address still recognise each other as on the same server.
Server flags
| Flag | Effect |
|---|---|
--headless |
No TUI, API only |
--playground |
Enable GraphiQL web IDE at GET /graphql |
--subsonic PORT |
Also serve the Subsonic API on a port of its own, for clients that expect one |
--port PORT |
Custom GraphQL port (default: 4000) |
--bind ADDR |
Bind address (default: 127.0.0.1) |
-d, --daemonize |
Detach and run in the background, logging to ~/.config/koan/koan.log. Implies --headless |
--api |
Serve the API alongside the TUI. Implied by --port, --bind, --subsonic and --playground |
--no-api |
Do not serve the API alongside the TUI, even with [graphql] enabled = true |
MCP is served at /mcp on the same port, with its own OAuth sign-in on server.url; see MCP Integration.
The TUI serves no API unless one of the flags above or [graphql] enabled = true asks it to. When it does, the setup page stays closed, so the first admin comes from koan auth setup.
A headless server indexes the library folders when it starts and again whenever they change, as the desktop app does.
Configuration
# config.local.toml — where this machine is reached
[server]
url = "https://music.example.com"
[graphql]
port = 4000 # the server's port
bind = "127.0.0.1" # bind address
playground = false # GraphiQL IDE
# config.local.toml — which machine serves Subsonic
[subsonic]
enabled = true # serve /rest/* on the main port
port = 4040 # and on a port of its own (optional)
# config.toml — waking iPhones through kōan's push relay
[push]
enabled = true # false keeps the server off the relayOr via environment variables:
export KOAN_SERVER__URL=https://music.example.com
export KOAN_GRAPHQL__PORT=8080
export KOAN_GRAPHQL__BIND=0.0.0.0
export KOAN_GRAPHQL__PLAYGROUND=true
export KOAN_PUSH__ENABLED=true # false keeps the server off the push relayUnder a path
kōan can share a host with other services at a path such as https://host.example/koan, which is how Tailscale Funnel puts several services on one name and port. Give server.url the path:
[server]
url = "https://host.example/koan"The server takes the path off each request before routing it, so a proxy may forward /koan/rest/ping as it is or strip it to /rest/ping (Funnel's --set-path strips it); both reach the same place. Redirects and cookies are given the path back, and the web UI and share pages link relative to it. Apps, the TUI and Subsonic clients are given the whole address, path included.
The path may use letters, digits, /, -, ., _ and ~, and may not begin with a segment kōan routes itself (/rest, /ui, /library, /share and the like), which a stripping proxy would make ambiguous; the server refuses to start with one.
The web UI then works only through that address: a browser that reaches the server directly, on its LAN address, is sent to /koan/…, which the server does not prefix for itself. Apps and Subsonic clients work on either.
An MCP client looks for the OAuth server's metadata between the host and the path, at https://host.example/.well-known/oauth-authorization-server/koan, which is outside what the proxy forwards for /koan. Forward that path to the same path on kōan, which answers it. With Funnel, as a second mount:
tailscale funnel --bg --set-path /koan http://127.0.0.1:4000
tailscale funnel --bg --set-path /.well-known/oauth-authorization-server/koan \
http://127.0.0.1:4000/.well-known/oauth-authorization-server/koanRemote TUI
Control a running headless kōan from a TUI on another machine. The server plays the audio; the TUI is a remote control:
koan play --server http://host:4000It follows the server's nowPlaying and queueUpdated subscriptions over /graphql/ws, so it hears of a change when it happens and sends nothing while nothing changes. A command the server refuses, and losing or regaining the server, show on the status line.
To play its library on the machine you are sitting at, sign in to it as a remote server instead (koan remote login, or Settings in the apps). Tracks then play through the local engine and download into the local cache like any other remote library.
Authentication
Auth is enabled by default. See Authentication for the full guide.
The first account
A new server has no accounts, and nothing can sign in until one exists. Until then the web UI answers with a setup page instead of sign-in: open the server in a browser, choose the admin's username and password, and you are signed in as that admin. The page closes for good once any account exists, however it was made.
Whoever reaches the setup page first becomes the admin, and the server logs a warning while it is open. On a server reachable from the internet, make the account as soon as it starts, or turn the page off and make the admin from a shell instead:
[graphql]
setup_wizard = false # or KOAN_GRAPHQL__SETUP_WIZARD=falseWith the page off, or for scripts, the first admin is made with koan auth setup, run on the server itself, against the same config directory the server uses. The server can be running at the time; it picks the account up on the next sign-in.
| Where the server runs | Run |
|---|---|
| Directly on a machine | koan auth setup |
docker run |
docker exec -it koan koan auth setup |
| Docker Compose | docker compose exec koan koan auth setup |
| Kubernetes | kubectl -n koan exec -it deploy/koan -- koan auth setup |
It asks for a username and offers to generate a password, which it prints once. To run it without a terminal, from a script or a CI job, pass both in the environment:
docker exec -e KOAN_USERNAME=admin -e KOAN_PASSWORD='…' koan koan auth setupOnce there is an admin, everything else is done signed in: the web UI's Users page, the apps' Settings, or GraphQL create accounts and send invites, so nobody else needs a shell. koan auth setup does nothing on a server that already has accounts; koan auth create-user adds one from the shell, and koan auth reset-password recovers an admin who is locked out.
The API binds to 127.0.0.1 by default. If you expose it on 0.0.0.0 with --bind 0.0.0.0, make sure auth is enabled (it is by default) or restrict access at the network level.
Cookie auth needs cookie_secure = false over plain HTTP, and browser clients need their origin listed in cors_origins. If you reach the server through a hostname, add it to allowed_hosts — anything else is refused. See Configuration.
To disable auth (localhost-only setups):
[graphql]
auth_enabled = falseWith auth disabled, anything that can reach the port is an admin; see Recovery / lockout before doing it.
Web UI
The server answers http://host:4000/ with a browser UI: the library, search, a play queue, playlists and share links, laid out for a phone as well as a desktop. Playback happens in the browser, streaming from the server; the server's own player is not involved. Media keys, headphone buttons and the system's now-playing controls drive it. Covers are resized once and kept in covers/ in the config directory, which is held to 4 GB by removing the covers read least recently; deleting it only costs regenerating them.
- Albums, artists and tracks sort and filter (name, favourites, recently played, lossless or codec, years, genre) through the page URL, the same filters the apps offer, so a filtered view can be bookmarked or sent.
- Playlists are the account's own and anyone's public ones, played or queued like an album. They are edited from the apps.
- Favourites lists the account's favourite artists, records and tracks. Recently played lists what it played in the last 30 days, each once. Both show the first few of each kind under a heading that gives the whole count and opens the matching filtered browser.
- History lists plays by day; any of them can be ticked and forgotten.
- Hearts on tracks, records and artists favourite them for the signed-in account. Every artist named in a collaboration's credit links to their own page.
- Artist pages hold the artist's own records and, under Features on, the records someone else is the album artist of that they are credited on.
On a phone, Playlists, Tracks, Recently played, Favourites and History sit under a Library tab, since the tab bar has room for six.
Track menu and properties
A track row's menu (right-click, press and hold on a phone, or its ⋯) offers play next, queue, favourite, share, and the album and artist.
Properties shows what the server knows about the track, for working out why a record appears twice or the wrong file plays: each of its sources (the file, and an entry from a remote server it syncs) with their tags and format, its uid and its album's, and its MusicBrainz ids. Admin accounts also see the file's full path on the server, with a copy button. Other accounts are not shown paths, since they describe the server's filesystem.
Rescan
Admin accounts find Rescan at the foot of the Library page, which the sidebar links for them on a wide screen as well as the phone's tab bar. It looks through the library folders for files added, changed or removed since the last scan, which the folder watcher normally does by itself. It is the same job as triggerScan, so a scan started from either shows in both.
Read every file again ignores the scan cache and reads every file's tags. An upgrade that reads more from tags needs this, since the files themselves did not change (triggerScan(reread: true)).
The section also shows the scans the server runs by itself, with what started each, how many of the files it has to read (new and changed ones, or every file on a re-read) it has read so far, and how it ended. A bar fills as it reads; while the scan is still finding out how many files that is, it shows a still band. The start-up scan after an upgrade that empties the scan cache reads every file and can take a long while.
Caches
Below Rescan, admin accounts see what the server keeps beside the library, so slow covers can be diagnosed without reading its logs: the cover cache's size against its 4 GB budget, how many covers it holds at each size and how many records it remembers as having no art, what the background warm is doing (making covers, idle, or paused because the cache is full) with how far it has got and when it runs next, and what the last sweep removed. A server syncing from another also shows its download cache, and every server its track, record and artist counts and how long the last scan took. The section updates as the warm, a sweep or a scan moves.
Warm now makes covers for the records still without them instead of waiting for the next pass, and Clear covers removes every kept cover, misses included, after saying how many and how much space that is. The same figures and actions are in GraphQL as serverCaches, warmCovers and clearCoverCache.
Signing in
Sign in with a kōan account (koan auth create-user). The session is the same pair of HttpOnly cookies the JSON login sets, so behind plain HTTP the UI needs cookie_secure = false, and a hostname it is reached by must be in allowed_hosts. The access cookie lasts access_token_ttl; an open page renews it from the refresh cookie, and a page loaded after it lapsed renews on the way in. With auth_enabled = false the UI is open to anyone who can reach the port.
Behind an authenticating proxy
When a proxy such as Authelia, Authentik or oauth2-proxy signs people in before they reach kōan, the web UI can take the account from the header the proxy sets instead of asking for a password:
[graphql]
proxy_auth_header = "Remote-User"
proxy_auth_from = ["172.18.0.5"] # the proxy's own addressThe header is believed only on a connection whose address is in proxy_auth_from, which names the proxy itself, not the clients behind it, and only when it carries a single value.
The account must already exist in kōan with exactly that name, byte for byte and case included: a name the server has no account for is refused, not created. A header from the proxy that names no one account (sent twice, merged, or not UTF-8) is refused too, and signs the browser out rather than leaving it on the session it had.
A session through the proxy is an access cookie alone, with no refresh cookie, and each page load and each renewal derives it again from the header. It therefore lasts no longer than the proxy's say-so: a browser whose proxy sign-in changes to another account is handed over on its next page load, and once the proxy stops naming an account (sign-out, or removal at the identity provider), what kōan issued for it lapses within access_token_ttl.
Signing out is done at the proxy. A password sign-in made without the proxy, such as koan auth login, keeps its refresh token as usual.
Turning proxy mode on does not end sessions signed in with a password before it: their refresh tokens still rotate at /auth/refresh. To end them, have each person sign out of the web UI once, or reset the account's password (koan auth reset-password, or Users in the web UI), which also revokes its API keys and app passwords and so signs its apps out too.
Proxy sign-in is on only when both settings are set. The server refuses to start, naming the problem, when one is set without the other, when the header is not a header name or an entry is neither an address nor a range, and when an entry covers every address (0.0.0.0/0, ::/0). When it is on, the server logs the header and the addresses it believes it from.
Name the proxy's own address rather than its network where you can. Anything else that connects from inside proxy_auth_from can name any account. Under Docker that includes the network's gateway (172.18.0.1 on 172.18.0.0/16), through which connections to a published port can arrive: from the host itself through docker-proxy, and from every client under rootless Docker or Docker Desktop. Do not publish kōan's port when it sits behind the proxy, and give the proxy a fixed address on the network (ipv4_address in Compose).
kōan reads the header only on web UI pages and the MCP consent page (/oauth/authorize), which the proxy must cover. Subsonic clients, kōan's apps and MCP clients cannot pass through an interactive proxy sign-in, so the proxy must let these through without its sign-in, and no others (each under the server's path, if it has one):
| Path | Used by |
|---|---|
/rest |
Subsonic clients and kōan's apps, including the koanLink WebSocket |
/graphql |
GraphQL clients |
/mcp |
MCP clients |
/auth/login, /auth/refresh, /auth/logout |
koan auth login and other token clients |
/oauth/register, /oauth/token |
MCP clients signing in |
/.well-known |
MCP clients discovering the OAuth server |
/share |
Public share links, for people without an account |
Exempt these exact paths, never whole /auth or /oauth prefixes. On a path the proxy does not cover it sets no header of its own, so whatever a client sent passes through from the proxy's address. Have the proxy remove the header from every incoming request before it authenticates, so a mistaken exemption carries no header at all. With Caddy:
music.example.com {
request_header -Remote-User
@public path /rest/* /graphql /graphql/* /mcp /mcp/* /auth/login /auth/refresh /auth/logout /oauth/register /oauth/token /.well-known/* /share/*
handle @public {
reverse_proxy koan:4000
}
handle {
forward_auth authelia:9091 {
uri /api/authz/forward-auth
copy_headers Remote-User
}
reverse_proxy koan:4000
}
}
With Traefik, a headers middleware that clears the header, placed before the forward-auth middleware on every router to kōan:
http:
middlewares:
strip-remote-user:
headers:
customRequestHeaders:
Remote-User: ""Subsonic clients
Besides playing, browsing and favourites, Subsonic clients get:
Favourites on every listing. A song, album or artist the account has favourited carries
starred, the time it was favourited, in the ID3 listings (album and artist pages, search, album lists, playlists, random songs) and in the folder browse (getIndexes' artists, and the albums and songsgetMusicDirectorylists), so a client shows its hearts without readinggetStarred2first. Ratings (userRating) and an album's last play (played) are carried in the same places.Ratings.
setRatingkeeps a rating of one to five per account for songs, albums and artists, returned asuserRating, andgetAlbumList2?type=highestlists rated albums best first. kōan's own apps do not show ratings.Bookmarks.
createBookmark,getBookmarksanddeleteBookmarkkeep one position and note per account and track, for clients that resume long tracks. kōan's own apps do not use them.A saved play queue.
savePlayQueueandgetPlayQueuekeep one queue per account, with its current song and position, for clients that save on pause or exit and resume on another device; the OpenSubsonicindexBasedQueueextension (savePlayQueueByIndex,getPlayQueueByIndex) names the current song by its place, so a song queued twice is unambiguous. Songs the library no longer has are left out when it is read.A queue holds at most 5,000 songs; a longer one is refused rather than cut. It needs an account: the shared secret is refused.
kōan's own apps move their queues between devices over the link, and use it only when a device is set to keep its queue on the server (see Remote servers).
Transcoding. A client that asks
streamfor a lowermaxBitRatethan the file's, or forformat=opus,mp3oraac, gets an encode made byffmpeg, so a lossless library does not cost full bandwidth on mobile data.format=rawanddownloadreturn the original. The limits, formats and fallbacks are in Configuration.A cover for every record.
getCoverArtfor a song, album or artist without art answers with the kōan ensō on a dark square, at the nearest size covers are served at, as Navidrome answers with its own placeholder, so a client always has an image to draw. It is marked with anX-Koan-Placeholderheader, which kōan's own apps read as "no artwork" and draw their placeholder in their own appearance instead. An id the library does not hold is still an error.Covers that do not touch the music. A record's cover is read from its files once, resized, and kept under the configuration directory (
covers/, at most 4 GB, the least recently read going first; covers an older version kept at sizes no longer served are removed at start); every latergetCoverArtfor it reads that one small file, so a grid of covers does not send a disk seeking through the library. A record's removal drops what was kept, and so does a change to its files or to a cover image beside them, whether the folder watcher sees it or a later scan does: on a network share or in a container, where the watcher hears nothing, the start-up and periodic scans compare the cover images with the ones they saw last. While it runs, the server makes every record's cover at the sizes the desktop app, the web UI and the phones' lists ask for (600 and 300) in the background, one at a time in the order the files lie, so the first request is quick too.Artist biographies and photographs.
getArtistInfo2answers with the opening of the artist's Wikipedia article and their photograph from Wikimedia Commons, found through the artist's MusicBrainz id and never by name, so an artist whose tags carry no id (on the artist or on one of their records) has none. The server looks up its whole library ahead of time, newest records' artists first, about one artist every few seconds to keep within MusicBrainz's and Wikimedia's limits, after each scan and once a day, refreshing what it found after a month and trying again a week after finding nothing. Photographs are kept in the cache directory (artists/). kōan's apps signed in to the server read both from it rather than asking MusicBrainz and Wikimedia themselves.Smart playlists, read-only, as ordinary playlists. See Smart playlists.
File paths, for admin accounts. Songs carry
path, the file's place relative to the library folder holding it (whole, for a file imported from outside every folder), so a client can show where a wrong or duplicated track comes from. Other accounts and the shared secret are not sent it, since it describes the server's filesystem. kōan's apps show it in a track's info as the path on the server.
Sign-in, and which credential each kind of client should use, is in Authentication.
Scrobbling
Each account can forward its plays to ListenBrainz, from the web UI's Scrobbling page (linked from Account), Settings → Integrations → Scrobbling in the Mac, iOS and Android apps, or the terminal UI's Settings, and to Last.fm, through the web UI's page, which the terminal UI's Settings also opens (see Last.fm). For ListenBrainz, paste the user token from its settings and the server checks it, then sends the plays already in the account's history and, from then on, every play kōan's apps and other Subsonic clients report (scrobble), with now-playing notices. It is the server that sends, so no client needs configuring, and a play reported once is forwarded once whichever device made it.
Plays wait in the database until ListenBrainz accepts them, so a restart or an outage delays them rather than losing them; the page shows how many are waiting. A token ListenBrainz stops accepting is shown there, and plays are kept until the account connects again. Plays the server's own player records are forwarded in the history sent on connecting, when they were listened to for half the track or four minutes, but not as they happen. Tracks without an artist or title are not sent.
Last.fm
Last.fm needs an API key and shared secret for the server, which its admin registers at https://www.last.fm/api/account/create and sets as lastfm.api_key and lastfm.secret in config.local.toml (see Configuration), and server.url, so that Last.fm can send people back.
The Scrobbling page then offers Connect Last.fm: it sends the person to Last.fm to approve kōan and back, and the server exchanges what Last.fm returns for a session key it keeps, never showing it.
The return address carries a one-time code made when the person left, so a link someone else makes cannot connect their Last.fm to your account. Without the key and secret the page says Last.fm is not set up.
Plays are sent as they are reported, fifty to a call, with now-playing notices, and wait in the database the same way. Last.fm ignores plays more than two weeks old, so connecting sends only the last two weeks of history, and a play still waiting past that is dropped rather than sent. A session key Last.fm stops accepting (the person revoked kōan there) is shown on the page, and plays are kept until the account connects again. Connecting Last.fm is done in the web UI; the apps show it in koanScrobbling as a service named lastfm and can disconnect it with service=lastfm.
For apps
The apps reach this through the koanScrobbling extension: koanScrobbling reports the account's connection (account name, plays waiting, and the error when the token was refused), koanScrobblingConnect takes a token in a form POST body, and only there, so that it stays out of access logs (one in the query string is ignored), and koanScrobblingDisconnect removes it (service=lastfm for Last.fm; ListenBrainz when none is named). The token is never sent back. The Apple TV app shows the connection but cannot change it, having no keyboard.
Sharing
A server makes share links itself: createShare (GraphQL, MCP, or a Subsonic client's own share button) returns <server.url>/share/<id>, a page anyone can open without an account, with a player for each shared track and a Download button that sends the shared files, untouched, as one zip. The server writes at most four zips at once and answers further downloads with 503 until one finishes; a download whose visitor stops reading for 30 seconds is ended.
A share is a slice of the library, shown the way the app shows it: one track shares its album cued to that track, an album the album, an artist their albums in release order, and several tracks stay a list. What a share covers is fixed when it is made; an artist share does not grow when the library does. Pages carry OpenGraph and Twitter card tags, with the cover as an absolute og:image on server.url, so a pasted link unfurls with its artwork.
The page and its audio answer for the share's own tracks and nothing else, addressed by position in the share rather than by library id. An expired, revoked or made-up id is the same 404. List shares with shares, set an expiry with updateShare, revoke with deleteShare. kōan's apps and terminal UI, signed in to this server, share through it.
Playing on a linked app
kōan's macOS, iOS, Android and Apple TV apps and the terminal UI, signed in to a kōan server, hold a WebSocket open to it at /rest/koanLink (authenticated like any other /rest call; a kōan extension, not part of OpenSubsonic). Down it the server sends commands; up it each app reports what it is playing, where it is in the track, and its queue.
{ clients { name platform playing nowPlaying positionMs queue { trackId title current } } }
mutation { playOnClient(trackIds: ["812", "813"]) { ok message } }
mutation { queueOnClientWhenAdded(artist: "Rilo Kiley", album: "Under the Blacklight") { id } }| Mutation | Does |
|---|---|
playOnClient(trackIds, startAt, enqueue) |
Replace the queue and play, or append with enqueue: true |
playNextOnClient(trackIds) |
Insert after the current track |
jumpOnClient(trackId) |
Play that track: from the queue, or slotted in after the current one |
removeFromClient(trackIds), clearClient |
Edit the queue |
controlClient(action), seekOnClient(positionMs) |
Pause, resume, next, previous; seek |
setPlayModeOnClient(shuffle, repeat) |
Shuffle on or off; repeat OFF, QUEUE or ONE |
setSleepTimerOnClient(minutes, endOf), cancelSleepTimerOnClient |
Fade out and pause after some minutes or at the end of the TRACK or RECORD, keeping the queue |
handOffClient(to, from) |
Move one app's queue and playhead to another and pause the first |
syncClient |
Pull what the server has added since the app last synced |
syncClients(full) |
Have every device of the account sync, now if linked, else when it next links |
evictOnClients(trackIds) |
Have every linked app delete its downloaded copies of those tracks, after a damaged file on the server is replaced |
queueOnClientWhenAdded(artist, album, playNext) |
Queue an album once it is in the library, e.g. one slsk is downloading. Checked after every library scan; lapses after a day. clientOrders lists them, cancelClientOrder withdraws one |
Every mutation that addresses one app, apart from handOffClient with its from and to, takes an optional client, an id or name from clients. Without it the server picks the app that is playing, else the one that played in the last six hours, else the only one linked, and otherwise answers with the choices so the caller can ask.
Track ids are the server's; an app that has not seen one syncs first, and its pages show what the sync brought in. Every account, admin included, sees and commands only its own apps, so a server shared by several people never sends one person's music to another's phone.
An app is linked while it runs. iOS suspends a backgrounded app that is not playing, and the server drops a link it has not heard from in 100 seconds. A server with [push] on, as it is by default, wakes a suspended phone through kōan's push relay to relink and take the command, choosing the one seen most recently when no client is named, since a reinstalled app leaves its old entry behind under the same name; a request to play arrives as a notification to tap, since iOS does not let an app start audio from the background. Opening the app relinks at once.
In a container
The image at ghcr.io/radiosilence/koan, for amd64 and arm64, runs koan --headless --bind 0.0.0.0, keeps config, database and auth keys in /config, and needs no sound card. latest and vX.Y.Z are releases; main and a commit sha follow the main branch between them.
Mount the library read-only, list it under [library] folders in /config/config.toml, and add the public hostname to allowed_hosts. Create the first admin on the setup page the web UI shows until one exists, or with koan auth setup inside the container (see The first account), and koan subsonic setup to enable the Subsonic API.
Set KOAN_SERVER__URL to the public address; the container does not start without it.
Kubernetes
The server needs one pod with two volumes: the library, read-only, and a state directory at /config that outlives the pod. It is a single SQLite index, so it runs as one replica, on one node. Set KOAN_LIBRARY__FOLDERS, KOAN_GRAPHQL__ALLOWED_HOSTS and KOAN_SERVER__URL as in the Compose example below, and terminate TLS in front of it.
With Pulumi
@radiosilence/koan-pulumi is a Pulumi component that deploys the server into a namespace. Its version is koan's: each release publishes both, and a pinned package deploys exactly that image.
It is published to GitHub Packages, which wants a token with read:packages even for public packages:
# .npmrc
@radiosilence:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}npm install @radiosilence/koan-pulumi @pulumi/kubernetes @pulumi/pulumi zodcreateKoan(provider, namespace, config) validates config against KoanConfSchema and creates a Deployment, a Service on port 80 and a NetworkPolicy. It creates no Ingress; it returns routes naming the Service and hostname, for whatever fronts the cluster to route.
import * as k8s from "@pulumi/kubernetes";
import { createKoan } from "@radiosilence/koan-pulumi";
const provider = new k8s.Provider("cluster", {});
const ns = new k8s.core.v1.Namespace("koan", { metadata: { name: "koan" } }, { provider });
const koan = createKoan(provider, ns.metadata.name, {
hostname: "music.example.com",
library: { existingClaim: "music" },
state: { existingClaim: "koan-state" },
push: { enabled: true }, // false keeps the server off kōan's push relay
});
export const routes = koan.routes;| Option | |
|---|---|
hostname |
Required. Becomes allowed_hosts and server.url (https://<hostname>), so TLS is expected in front |
library |
Required: existingClaim or hostPath. Mounted read-only at /music |
state |
existingClaim or hostPath, mounted at /config. Unset, it is an emptyDir and the index and accounts go with the pod |
image |
repository, tag (defaults to the package's version), pullPolicy |
nodeSelector |
Needed with a hostPath, which is one node's disk |
push |
enabled (default true): whether the server wakes the iOS app through kōan's push relay when it is suspended. Set enabled: false to keep the server off the relay |
resources |
Requests default to 250m / 256Mi, limits to 6 CPU / 5Gi |
networkPolicy |
On by default. Ingress only from api.from (a Traefik pod by default) plus extraIngress; egress to cluster DNS and the public internet, with privateCidrs excluded |
With persistent state, each update first runs koan check-db in a Job against a snapshot of the live database. If the new version's migration fails there, the update stops and the old pod keeps serving. kubelet creates a missing hostPath as root, and koan runs as uid 1000, so an init container hands the state directory to that uid before the server starts; initPermissions.enabled: false turns it off. The root filesystem is read-only, and the artwork and lyrics caches live in an emptyDir, rebuilt after a restart.
Unknown options are rejected rather than ignored, so a stack carrying options a newer package removed fails at pulumi preview.
Two servers during an upgrade
Two koan processes can share one state directory on one node for the minutes an upgrade overlaps them: SQLite's WAL lets both read and write. The state directory must be on a local filesystem, which WAL needs anyway and the lock below relies on. Only one scans and watches the library, whichever holds watch.lock beside the database; the other serves and waits on the lock, taking over the moment the first exits, however it exits. A build older than the database refuses to start, naming the schema versions, rather than serving errors.
A release that changes the schema is covered too. The new server migrates on start in one transaction, so the old one, mid-request, sees the old schema or the new one and never a mixture, and a migration that fails leaves the database as it was. From the moment it commits, the old server refuses every database connection it is asked for, drains as it would on SIGTERM and exits, so it never writes the old shape into the new schema; what fails is the requests it had in flight at that moment. Devices linked to the outgoing server reconnect to the new one, as after any restart.
Once it is running, create the admin account in the pod:
kubectl -n koan exec -it deploy/koan -- koan auth setupDocker Compose
kōan behind Caddy, which obtains and renews the TLS certificate. Save as compose.yaml:
services:
koan:
image: ghcr.io/radiosilence/koan:latest
restart: unless-stopped
environment:
KOAN_LIBRARY__FOLDERS: '["/music"]'
KOAN_GRAPHQL__ALLOWED_HOSTS: '["${KOAN_HOST:?set KOAN_HOST to the server hostname}"]'
KOAN_GRAPHQL__COOKIE_SECURE: "true"
KOAN_SERVER__URL: https://${KOAN_HOST}
KOAN_SUBSONIC__ENABLED: "true"
KOAN_PUSH__ENABLED: "true" # "false" keeps the server off kōan's push relay
volumes:
# The image runs as uid 1000; a bind mount here has to be writable by it.
- koan-config:/config
- ${MUSIC:?set MUSIC to the music folder}:/music:ro
caddy:
image: caddy:2
restart: unless-stopped
ports: ["80:80", "443:443", "443:443/udp"]
command: caddy reverse-proxy --from ${KOAN_HOST} --to koan:4000
volumes:
- caddy-data:/data
volumes:
koan-config:
caddy-data:On a machine whose hostname resolves to it, with ports 80 and 443 open:
KOAN_HOST=music.example.com MUSIC=/mnt/music docker compose up -d
docker compose exec koan koan auth setup # the admin accountThen open https://music.example.com and sign in. The Subsonic API is on for kōan accounts; koan subsonic setup adds a shared secret for clients that have none. Config, the database and keys live in the koan-config volume. The image runs as uid 1000, so a bind mount in its place has to be writable by that uid.