Skip to content

Navidrome -- Runbook

Common Tasks

Trigger library rescan

Navidrome auto-scans every 15 minutes. To force an immediate scan:

# Via API
curl -u admin:PASSWORD "https://music.eva-00.network/api/scan" -X POST

# Or restart the container (triggers scan on startup)
ssh [email protected] docker restart navidrome

Create a new user

Navidrome web UI: Settings > Users > Add User

Reset admin password

  1. Update password in Vault via vault-write workflow
  2. SSH into the LXC and reset via Navidrome CLI:
ssh [email protected]
docker exec -it navidrome /app/navidrome user setpassword admin NEW_PASSWORD

Check container status

ssh [email protected] docker ps

Expected: navidrome, yubal, alloy all running.

View logs

# Navidrome logs
ssh [email protected] docker logs navidrome --tail 50

# Yubal logs
ssh [email protected] docker logs yubal --tail 50

# Or via Grafana Loki
# {container_name="navidrome"}
# {container_name="yubal"}

Yubal Operations

Manual download (single album/playlist)

Access Yubal web UI at http://192.168.1.132:8000 and paste a YouTube Music URL.

Alternatively, use the Yubal browser extension (Firefox/Chrome) to one-click download from YouTube Music pages.

Check sync status

ssh [email protected] docker logs yubal --tail 20

Re-authenticate YouTube Music

If Yubal stops downloading (auth expired):

  1. Access Yubal web UI at http://192.168.1.132:8000
  2. Follow the OAuth re-authentication flow
  3. Yubal stores the token in /opt/yubal/config/

Change sync schedule

Edit services/navidrome/docker-compose.yml, update YUBAL_SCHEDULER_CRON, push to trigger redeployment.

Troubleshooting

Music not appearing after Yubal download

  1. Check Yubal downloaded successfully: docker logs yubal --tail 30
  2. Verify files exist on disk: ls /music/ on LXC 132
  3. Check Navidrome scan status in web UI (bottom of page shows scan progress)
  4. Force rescan: curl -u admin:PASSWORD "https://music.eva-00.network/api/scan" -X POST

Mobile app can't connect

  1. Verify Navidrome is running: curl http://192.168.1.132:4533/ping
  2. Verify Caddy routing: curl -I https://music.eva-00.network
  3. In the iOS app, use these settings:
  4. Server URL: https://music.eva-00.network
  5. Username: your Navidrome username
  6. Password: your Navidrome password
  7. If connecting remotely, ensure NetBird VPN is active
ssh [email protected]
docker logs navidrome
# Check for permission issues on /data or /music
ls -la /opt/navidrome/data/
ls -la /music/

Yubal download failures

ssh [email protected] docker logs yubal --tail 50

Common issues: - Auth expired: Re-authenticate via web UI or re-upload cookies (see below) - Rate limited: Yubal handles this automatically with backoff - Disk full: Check unohana usage: df -h /music - Permission denied on /app/data: Host directory /mnt/all-might/music must be owned by 101000:101000 (maps to UID 1000/yubal inside unprivileged LXC). Fix: ssh [email protected] "chown -R 101000:101000 /mnt/all-might/music"

YouTube Music cookies

For private playlists or age-restricted content, Yubal needs YouTube cookies:

  1. Install "Get cookies.txt LOCALLY" browser extension
  2. Go to https://music.youtube.com (logged in)
  3. Click extension > Export (not "Export all") > Netscape format
  4. Upload via Yubal web UI, or place directly at /opt/yubal/config/ytdlp/cookies.txt on LXC 132

Cookies may expire periodically -- re-export and re-upload when downloads fail with auth errors.

Custom Image

Rebuild with new themes

  1. Add theme files to homelab/navidrome-custom repo (themes/ directory)
  2. Push to main -- build workflow triggers automatically
  3. Redeploy Navidrome to pull new image

Rebuild with upstream update

Dispatch the build workflow with a specific version:

# Via Forgejo UI: homelab/navidrome-custom > Actions > Run workflow
# Set navidrome_version to e.g. "0.61.2" or "latest"

Then redeploy Navidrome to pull the new image.

Redeploy

Trigger via Forgejo Actions:

  1. Go to https://git.eva-00.network/holo/chizuru-v2/actions
  2. Find "Deploy Navidrome" workflow
  3. Click "Run workflow"
  4. Set force_clean=true only if you want to wipe all data

Or push changes to services/navidrome/** or ansible/playbooks/navidrome.yml to trigger automatically.