navidrome-litefs/conductor/archive/fix_navidrome_paths_20260209/spec.md

Specification: Correct Navidrome Database and Plugins Location (fix_navidrome_paths)

Overview

Force Navidrome to use the /data LiteFS mount for its SQLite database by setting the DATAFOLDER to /data. To avoid the "Operation not permitted" error caused by LiteFS's restriction on directory creation, redirect the Navidrome plugins folder to persistent shared storage.

Functional Requirements

• Nomad Job Configuration (navidrome-litefs-v2.nomad):
  • Set ND_DATAFOLDER="/data". This will force Navidrome to create and use navidrome.db on the LiteFS mount.
  • Set ND_PLUGINSFOLDER="/shared_data/plugins". This prevents Navidrome from attempting to create a plugins directory in the read-only/virtual /data mount.
  • Keep ND_CACHEFOLDER and ND_BACKUP_PATH pointing to /shared_data subdirectories.
• Entrypoint Logic (entrypoint.sh):
  • Ensure it creates /shared_data/plugins if it doesn't exist.
  • Remove the explicit export ND_DATABASE_PATH if it conflicts with the new DATAFOLDER logic, or keep it as an explicit override.
• Verification:
  • Confirm via lsof that Navidrome is finally using /data/navidrome.db.
  • Confirm that LiteFS /debug/vars now reports the database in its active set.

Non-Functional Requirements

• Persistence: Ensure all non-database files (plugins, cache, backups) are stored on the shared host mount (/shared_data) to survive container restarts and migrations.

Acceptance Criteria

• Navidrome successfully starts with /data as its data folder.
• No "Operation not permitted" errors occur during startup.
• lsof confirms /data/navidrome.db is open by the Navidrome process.
• LiteFS txid increases on the Primary and replicates to Replicas when Navidrome writes to the DB.