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

Specification: Fix LiteFS Configuration and Process Management (fix_litefs_config)

Overview

Reconfigure the Navidrome/LiteFS process management to ensure Navidrome and its Consul service registration only occur on the Primary node. This will be achieved by leveraging the LiteFS exec block and updating the entrypoint.sh logic. Additionally, correct the Navidrome database and storage paths to properly utilize the LiteFS replicated mount.

Functional Requirements

• LiteFS Configuration (litefs.yml):
  • Enable the exec block to trigger /usr/local/bin/entrypoint.sh.
  • This allows LiteFS to manage the lifecycle of the application.
• Entrypoint Logic (entrypoint.sh):
  • Implement a supervision loop that monitors leadership via the /data/.primary file.
  • On Primary:
    • Register the node as the navidrome (primary) service in Consul.
    • Start the Navidrome process.
  • On Replica:
    • Ensure Navidrome is NOT running.
    • Deregister the navidrome primary service if previously registered.
    • (Optional) Register as a replica service or simply wait.
  • On Transition: Handle graceful shutdown of Navidrome if the node loses leadership.
• Storage and Path Configuration (navidrome-litefs-v2.nomad):
  • Set ND_DATAFOLDER to /data (the LiteFS FUSE mount).
  • Set ND_CACHEFOLDER to /shared_data/cache (shared persistent storage).
  • Set ND_BACKUP_PATH to /shared_data/backup (shared persistent storage).
• Dockerfile Updates:
  • Update ENTRYPOINT to ["litefs", "mount"] to allow LiteFS to act as the supervisor.

Non-Functional Requirements

• Robustness: Use a simple bash loop for process management to avoid extra dependencies.
• Signal Handling: Ensure signals (SIGTERM) are correctly forwarded to Navidrome for graceful shutdown.

Acceptance Criteria

• Navidrome process runs ONLY on the Primary node.
• Consul service navidrome correctly points to the current Primary.
• Navidrome database (navidrome.db) is confirmed to be on the /data mount.
• Cluster failover correctly stops Navidrome on the old primary and starts it on the new one.

Out of Scope

• Implementation of complex init systems like tini (bash loop selected by user).