musicdl-catalog-sync-suite/Music_Server/docs/nas-docker-deployment.md

NAS Docker Deployment

This deployment is tailored for the Synology NAS at 192.168.5.43.

Host Paths

• Source catalog DB: /volume4/Music_Cloud/catalogsync/data/catalogsync.db
• Source music library: /volume4/Music_Cloud/library
• App workspace: /volume4/Music_Cloud/Music_Server
• Repo checkout: /volume4/Music_Cloud/Music_Server/app
• Runtime config: /volume4/Music_Cloud/Music_Server/config/music_server.env
• Runtime data: /volume4/Music_Cloud/Music_Server/data/catalog_read.db
• Deploy script: /volume4/Music_Cloud/Music_Server/bin/deploy_and_restart.sh

Tracked Files

• Docker image: Dockerfile
• NAS compose: docker-compose.nas.yml
• Example env: music_server.env.example
• Catalog export script: export_catalog_read.py
• Local deploy entry: deploy-music-server.ps1
• Deploy delegate: deploy_to_nas.ps1
• Deploy helper: deploy_to_nas.py
• NAS deploy template: deploy_and_restart.sh

Dependency on catalog-sync Post-Download Export

Music_Server depends on catalog-sync to refresh /volume4/Music_Cloud/Music_Server/data/catalog_read.db automatically after downloads.

Configure the following in catalog-sync:

• CATALOG_EXPORT_COMMAND=bash /volume4/Music_Cloud/Music_Server/scripts/catalog-export.sh
• CATALOG_EXPORT_WORKDIR=/volume4/Music_Cloud/Music_Server

If this automation is not configured, Music_Server will only see new catalog data after a manual export.

First-Time Setup

1. Copy the repo to /volume4/Music_Cloud/Music_Server/app.
2. Create /volume4/Music_Cloud/Music_Server/config and copy app/config/music_server.env.example to /volume4/Music_Cloud/Music_Server/config/music_server.env.
3. Create /volume4/Music_Cloud/Music_Server/data.
4. Set a real PUBLIC_MUSIC_ACCESS_TOKEN.
5. Set MUSIC_SERVER_DISABLE_AUTH=1 only if you explicitly want to disable token auth.
6. Run the export job:

sudo docker-compose -f docker-compose.nas.yml run --rm catalog-export

7. Start the service:

sudo docker-compose -f docker-compose.nas.yml up -d music-server

The NAS compose file is intentionally wired to ../config and ../data, so runtime state survives app-checkout replacement during deploy.

Standard Deploy Flow

From this Windows workstation, run:

powershell -ExecutionPolicy Bypass -File .\deploy-music-server.ps1

What it does:

• Upload the repository into NAS staging: /volume4/Music_Cloud/Music_Server/deploy/staging/music-server-app
• Install/update /volume4/Music_Cloud/Music_Server/bin/deploy_and_restart.sh
• On NAS, move legacy runtime files from app/config and app/data into the standard sibling config and data directories when needed
• Rebuild images, rerun catalog-export, restart music-server, then probe http://127.0.0.1:18081/healthz
• Keep timestamped app backups under /volume4/Music_Cloud/Music_Server/deploy/backups

Smoke Tests

• Health: http://<nas-ip>:18081/healthz
• Token status: GET /auth/v1/token-status
• Plugin manifest: GET /plugins/music_server.json
• Plugin asset: GET /plugins/music_server.js
• MusicFree catalog: GET /mf/v1/recommend/sheets
• Stream resolve: POST /mf/v1/media/resolve

The service can stream local files directly from /volume4/Music_Cloud/library through the mounted /music_library volume when public_url is absent.

Token Operations

Issue a token:

python -m music_server.tools.issue_token --days 90 --label iphone16

List tokens:

python -m music_server.tools.list_tokens

Unbind a token from its current client:

python -m music_server.tools.unbind_token --token-id <token_id>

Revoke a token:

python -m music_server.tools.revoke_token --token-id <token_id> --reason replaced

Smoke check token status:

curl -H "Authorization: Bearer <token>" -H "X-Music-Client-Id: smoke-client" http://127.0.0.1:18081/auth/v1/token-status

Smoke check plugin manifest:

curl http://127.0.0.1:18081/plugins/music_server.json

Notes

• The default Dockerfile base image uses docker.m.daocloud.io/library/python:3.11-slim so NAS builds do not depend on direct Docker Hub access.
• If your NAS has a different preferred mirror, override BASE_IMAGE during build.