127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# 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.
|