navidrome-litefs/conductor/tracks/fix_routing_20260207/plan.md

Implementation Plan: Direct Primary Routing for Navidrome-LiteFS

This plan outlines the steps to reconfigure the Navidrome-LiteFS cluster to bypass the LiteFS write-forwarding proxy and use direct primary node routing for improved reliability and performance.

Phase 1: Infrastructure Configuration Update [checkpoint: 5a57902]

In this phase, we will modify the Nomad job and LiteFS configuration to support direct port access and primary-aware health checks.

• Task: Update navidrome-litefs-v2.nomad to point service directly to Navidrome port
  • Modify service block to use port 4533 instead of dynamic mapped port.
  • Replace HTTP health check with a script check running litefs is-primary.
• Task: Update litefs.yml to ensure consistent internal API binding (if needed)
• Task: Conductor - User Manual Verification 'Infrastructure Configuration Update' (Protocol in workflow.md)

Phase 2: Deployment and Validation

In this phase, we will deploy the changes and verify that the cluster correctly handles primary election and routing.

• Task: Deploy updated Nomad job
  • Execute nomad job run navidrome-litefs-v2.nomad.
• Task: Verify Consul health status
  • Confirm that only the LiteFS primary node is marked as passing.
  • Confirm that replica nodes are marked as critical.
• Task: Verify Ingress Routing
  • Confirm Traefik correctly routes traffic only to the primary node.
  • Verify that Navidrome is accessible and functional.
• Task: Conductor - User Manual Verification 'Deployment and Validation' (Protocol in workflow.md)