mirror of
https://github.com/Dvorinka/swingmusic-extended.git
synced 2026-06-03 20:13:02 +00:00
Tomas Dvorak
118 lines
3.2 KiB
Markdown
118 lines
3.2 KiB
Markdown
# CasaOS Deployment Guide
|
|
|
|
## Why CasaOS Was Failing
|
|
|
|
The backend can fail in containerized environments when no static web client is bundled.
|
|
If `client.zip` is not available at runtime, the server may try to fetch web assets dynamically, which is fragile on appliance-like deployments.
|
|
|
|
## What Is Fixed In This Repo
|
|
|
|
- `Dockerfile` is now multi-stage and bundles webclient assets into `/app/client`.
|
|
- Runtime now uses `SWINGMUSIC_CLIENT_DIR=/app/client`.
|
|
- Compose has health checks for backend + Dragonfly.
|
|
- Added `docker-compose.casaos.yml` with CasaOS-friendly path/environment defaults.
|
|
|
|
## 1) Build Image On The CasaOS Host
|
|
|
|
Run on your CasaOS machine from this repository root:
|
|
|
|
```bash
|
|
docker build -t swingmusic-local:latest .
|
|
```
|
|
|
|
If you prefer a registry image, set `SWINGMUSIC_IMAGE` accordingly in step 2.
|
|
|
|
## 2) Use CasaOS-Friendly Compose
|
|
|
|
Use [`docker-compose.casaos.yml`](/home/tdvorak/Desktop/PROG+HTML/SwingMusic/docker-compose.casaos.yml) as your custom app compose.
|
|
|
|
Important env values:
|
|
|
|
- `SWINGMUSIC_IMAGE` default: `swingmusic-local:latest`
|
|
- `SWINGMUSIC_PORT` default: `1970`
|
|
- `SWINGMUSIC_MUSIC_DIR` default: `/DATA/Media/Music`
|
|
- `SWINGMUSIC_CONFIG_DIR` default: `/DATA/AppData/swingmusic/config`
|
|
- `SWINGMUSIC_DRAGONFLY_DIR` default: `/DATA/AppData/swingmusic/dragonfly`
|
|
|
|
Pre-create and permission-check app data dirs:
|
|
|
|
```bash
|
|
mkdir -p /DATA/AppData/swingmusic/config /DATA/AppData/swingmusic/dragonfly
|
|
chmod -R 775 /DATA/AppData/swingmusic
|
|
```
|
|
|
|
## 3) Smoke Test
|
|
|
|
After app starts:
|
|
|
|
```bash
|
|
curl -sS http://127.0.0.1:1970/healthz
|
|
```
|
|
|
|
Expected: JSON with `"ok": true`.
|
|
|
|
Then open:
|
|
|
|
- `http://<casaos-host-ip>:1970/`
|
|
- Complete setup (owner + music directory).
|
|
|
|
## 4) Verify Auth Flows (Web + Mobile + Desktop)
|
|
|
|
From web UI:
|
|
|
|
1. Login.
|
|
2. Generate pairing QR/code.
|
|
3. Mobile: scan QR or enter `server_url|pair_code` manually.
|
|
4. Desktop: use manual URL + pair code or URL + username/password.
|
|
|
|
Expected behavior:
|
|
|
|
- Unauthenticated clients are blocked from main app.
|
|
- `/auth/pair` code is single-use (first 200, second 400).
|
|
- Protected APIs return 401 without token.
|
|
|
|
## 5) If It Still Fails In CasaOS
|
|
|
|
Check container status:
|
|
|
|
```bash
|
|
docker ps -a | grep -E 'swingmusic|dragonfly'
|
|
```
|
|
|
|
Or run the bundled diagnostics script:
|
|
|
|
```bash
|
|
./scripts/casaos-diagnose.sh
|
|
```
|
|
|
|
Check logs:
|
|
|
|
```bash
|
|
docker logs --tail 200 swingmusic
|
|
docker logs --tail 200 swingmusic-dragonfly
|
|
```
|
|
|
|
Check rendered compose:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.casaos.yml config
|
|
```
|
|
|
|
Common issues:
|
|
|
|
1. Image missing:
|
|
- Build image first or set `SWINGMUSIC_IMAGE` to a valid registry tag.
|
|
2. Port conflict on `1970` or `6379`:
|
|
- Change `SWINGMUSIC_PORT` / `DRAGONFLY_PORT`.
|
|
3. Permission denied on `/DATA/AppData/...`:
|
|
- Fix host dir ownership/permissions.
|
|
4. DNS/pull failures:
|
|
- Confirm CasaOS host can pull `docker.dragonflydb.io/dragonflydb/dragonfly`.
|
|
|
|
## Notes About CasaOS Compose Compatibility
|
|
|
|
- CasaOS AppStore release notes mention Docker Compose engine upgrades to support newer compose formats:
|
|
https://github.com/IceWhaleTech/CasaOS-AppStore/releases
|
|
- Many CasaOS app templates map persistent data under `/DATA/AppData/$AppID/...`:
|
|
https://community.bigbeartechworld.com/t/no-update-for-immich/4089/4
|