# 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