From 94f5dec4c84ad7cb20f450fb2e7a90c210979510 Mon Sep 17 00:00:00 2001 From: lukepurnell Date: Thu, 28 May 2026 08:37:19 +0100 Subject: [PATCH 1/2] docs: add macOS bind mount caveat for Docker installation --- content/en/docs/installation/docker.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/en/docs/installation/docker.md b/content/en/docs/installation/docker.md index c648eb2f..c4f1ca9b 100644 --- a/content/en/docs/installation/docker.md +++ b/content/en/docs/installation/docker.md @@ -58,3 +58,11 @@ $ docker run -d \ file. For `docker` cli use the `-e` parameter. Ex: `-e ND_SESSIONTIMEOUT=24h`. - If you want to use a [configuration file](/docs/usage/configuration/options/#configuration-file) with Navidrome running in Docker, you can create a `navidrome.toml` config file in the `/data` folder and set the option `ND_CONFIGFILE=/data/navidrome.toml`. + +### MacOS Docker Desktop: bind mount caveat + +When running Navidrome on Docker Desktop for macOS, using a host bind mount for the `/data` and `/music` directories may lead to filesystem-related issues such as disk I/O errors under certain workloads. + +This appears to be related to the filesystem translation layer between macOS (APFS) and the Linux filesystem used inside the Docker VM (via VirtioFS / shared file systems). Under heavy or frequent disk activity (e.g. SQLite writes or library scanning), some users have reported instability or I/O errors. + +A more reliable alternative on macOS is to use a Docker-managed volume for `/data` From 2a6eb5222e55a3f19bba85fec38112aa25a204e9 Mon Sep 17 00:00:00 2001 From: laker-93 Date: Thu, 28 May 2026 08:42:05 +0100 Subject: [PATCH 2/2] Fix wording for Docker-managed volumes in macOS section --- content/en/docs/installation/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/installation/docker.md b/content/en/docs/installation/docker.md index c4f1ca9b..52a8c3cf 100644 --- a/content/en/docs/installation/docker.md +++ b/content/en/docs/installation/docker.md @@ -65,4 +65,4 @@ When running Navidrome on Docker Desktop for macOS, using a host bind mount for This appears to be related to the filesystem translation layer between macOS (APFS) and the Linux filesystem used inside the Docker VM (via VirtioFS / shared file systems). Under heavy or frequent disk activity (e.g. SQLite writes or library scanning), some users have reported instability or I/O errors. -A more reliable alternative on macOS is to use a Docker-managed volume for `/data` +A more reliable alternative on macOS is to use a Docker-managed volumes.