Initial import: Music_Server, MusicFree, catalog-sync
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user