swingmusic-extended/CASAOS_DEPLOYMENT.md

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:

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

mkdir -p /DATA/AppData/swingmusic/config /DATA/AppData/swingmusic/dragonfly
chmod -R 775 /DATA/AppData/swingmusic

3) Smoke Test

After app starts:

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:

docker ps -a | grep -E 'swingmusic|dragonfly'

Or run the bundled diagnostics script:

./scripts/casaos-diagnose.sh

Check logs:

docker logs --tail 200 swingmusic
docker logs --tail 200 swingmusic-dragonfly

Check rendered compose:

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