# 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](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/Dockerfile)
- NAS compose: [docker-compose.nas.yml](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/docker-compose.nas.yml)
- Example env: [music_server.env.example](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/config/music_server.env.example)
- Catalog export script: [export_catalog_read.py](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/scripts/export_catalog_read.py)
- Local deploy entry: [deploy-music-server.ps1](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/deploy-music-server.ps1)
- Deploy delegate: [deploy_to_nas.ps1](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/scripts/deploy_to_nas.ps1)
- Deploy helper: [deploy_to_nas.py](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/scripts/deploy_to_nas.py)
- NAS deploy template: [deploy_and_restart.sh](/d:/source/musicdl-catalog-sync-worktrees/Music_Server/scripts/templates/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:

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

7. Start the service:

```bash
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
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:

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

List tokens:

```bash
python -m music_server.tools.list_tokens
```

Unbind a token from its current client:

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

Revoke a token:

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

Smoke check token status:

```bash
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:

```bash
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.