refactor(docker): default compose builds from Dockerfiles (baked deps, cached)

Chosen flow: build on the host from backend/scrobble Dockerfiles instead of
pulling from a registry (no registry / no Docker-on-dev needed). Heavy deps are
baked, so restarts are instant and rebuilds after git pull are cache-fast.
Removed the now-obsolete docker-compose.dev.yml (runtime-install variant); the
optional push-to-registry script stays for a future CI flow. Updated README,
CLAUDE.md, .env.example.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -1,5 +1,6 @@
 # Copy to .env next to your docker-compose file and fill in.  cp .env.example .env
-# Used by docker-compose.yml (pulls pre-built images) AND docker-compose.dev.yml (build-on-host).
+# Used by docker-compose.yml (builds locally from the Dockerfiles).
+# The REGISTRY/TAG at the bottom are only for the optional pull-from-registry / CI flow.
 
 # ── URLs pre-filled on the frontend setup screen ─────────────────────────────
 NAVIDROME_URL=https://music.example.com

CLAUDE.md

@@ -41,14 +41,13 @@ npm run build    # production build → dist/
 npm run preview  # preview the production build
 ```
 
-Backend runs in Docker. Two compose files:
-- **`docker-compose.yml`** (default/production) — PULLS pre-built images (deps baked into
-  `backend/Dockerfile` + `scrobble/Dockerfile`), so restarts are instant. Build+push from dev with
-  `npm run push-images` (needs `REGISTRY`/`TAG` in `.env`), then on the host `docker compose pull &&
-  docker compose up -d`. See `.env.example`.
-- **`docker-compose.dev.yml`** — builds on the host (mounts `./backend`, installs deps at container
-  start). Restart after backend changes: `docker compose -f docker-compose.dev.yml restart
-  novasonic-backend` (re-pulls yt-dlp).
+Backend runs in Docker via **`docker-compose.yml`**, which **builds locally from the Dockerfiles**
+(`backend/Dockerfile` + `scrobble/Dockerfile`). The heavy deps (ffmpeg, Deno, yt-dlp, node libs) are
+baked into the images, so container **restarts are instant** and a rebuild after `git pull` is fast
+(Docker caches the dep layers — only the code COPY layer changes). Deploy: `git pull && docker compose
+up -d --build`; a plain restart is `docker compose restart novasonic-backend` (the backend also
+re-pulls the latest yt-dlp on each start). No registry needed — an optional pull-from-registry / CI
+flow can build the same Dockerfiles elsewhere and push (`scripts/build-push-images.mjs`, `.env.example`).
 
 On the deploy host the music lives at `/opt/navidrome/music`.
 

README.md

@@ -122,14 +122,13 @@ TICKETMASTER_API_KEY=  # optional — free key from developer.ticketmaster.com
 
 ### 2. Start
 
-Build the images on the host (simplest — no registry needed):
-
 ```bash
-docker compose -f docker-compose.dev.yml up -d
+docker compose up -d --build
 ```
 
-The default `docker-compose.yml` instead **pulls pre-built images** from a registry (faster restarts;
-set `REGISTRY`/`TAG` in `.env`, `npm run push-images` from a dev machine, then `docker compose up -d`).
+Builds locally from the Dockerfiles (deps baked in → instant restarts; rebuilds after a `git pull`
+are fast thanks to Docker's layer cache). No registry needed. (An optional pull-from-registry / CI
+flow exists too — `npm run push-images` + `REGISTRY`/`TAG` in `.env`, see `.env.example`.)
 
 Frontend on port 8080, backend on port 3700, scrobble service on port 3710. Route each through your reverse proxy. **Important:** the scrobble subdomain must *not* sit behind an SSO / forward-auth gateway — it authenticates itself via Navidrome (`ping.view`), and a gateway in front redirects the app's API calls to a login page.
 

docker-compose.dev.yml

@@ -1,75 +0,0 @@
-services:
-
-  # ── Frontend (nginx) ──────────────────────────────────────────────────────────
-  novasonic-frontend:
-    build: .
-    container_name: novasonic-frontend
-    restart: unless-stopped
-    ports:
-      - "8080:80"          # route this port through your reverse proxy
-    environment:
-      - NAVIDROME_URL=${NAVIDROME_URL}   # pre-filled on the setup screen
-      - BACKEND_URL=${BACKEND_URL}       # pre-filled on the setup screen
-      - SCROBBLE_URL=${SCROBBLE_URL}     # play-log / stats service (setup screen)
-
-  # ── Backend (yt-dlp download server) ─────────────────────────────────────────
-  novasonic-backend:
-    image: node:22-slim
-    container_name: novasonic-backend
-    restart: unless-stopped
-    working_dir: /app
-    volumes:
-      - ./backend:/app:ro                # mount entire backend dir (server + lib/)
-      - ${MUSIC_PATH}:${MUSIC_PATH}      # exact path from .env, no remapping
-      - novasonic-data:/data             # writable data dir for overrides, state, etc.
-    ports:
-      - "3700:3700"                      # route this port through your reverse proxy
-    environment:
-      - PORT=3700
-      - MUSIC_PATH=${MUSIC_PATH}         # same path inside the container
-      - DATA_PATH=/data
-      - AUDIO_FMT=${AUDIO_FMT:-mp3}
-      - AUDIO_QUALITY=${AUDIO_QUALITY:-0}
-      - MAX_PARALLEL=${MAX_PARALLEL:-2}
-      - DOWNLOAD_BACKEND=${DOWNLOAD_BACKEND:-ytdlp}
-      - TICKETMASTER_API_KEY=${TICKETMASTER_API_KEY}
-      # Android APK download button — backend proxies a fixed Gitea release ("apk-latest"), same LAN.
-      # Optional: leave unset to use the local /data/novasonic.apk fallback instead.
-      - GITEA_URL=${GITEA_URL:-}                 # internal Gitea base, e.g. http://gitea:3000
-      - GITEA_REPO=${GITEA_REPO:-}               # owner/repo, e.g. Docker/NovaSonic
-      - GITEA_TOKEN=${GITEA_TOKEN:-}             # read token (only for a private repo)
-      - GITEA_APK_TAG=${GITEA_APK_TAG:-apk-latest}
-    command: >
-      sh -c "
-        apt-get update && apt-get install -y --no-install-recommends python3 python3-pip ffmpeg curl git unzip && rm -rf /var/lib/apt/lists/* &&
-        pip install --break-system-packages -U --pre 'yt-dlp[default]' &&
-        curl -fsSL https://deno.land/install.sh | sh &&
-        pip install --break-system-packages spotapi 'git+https://github.com/TzurSoffer/spotify-downloader' &&
-        mkdir -p /deps && cd /deps && npm install express kuromoji &&
-        cd /app && PATH=/root/.deno/bin:$$PATH NODE_PATH=/deps/node_modules node novasonic-server.js
-      "
-
-  # ── Scrobble service (isolated timestamped play-log → stats + Wrapped) ────────
-  novasonic-scrobble:
-    image: node:22-slim
-    container_name: novasonic-scrobble
-    restart: unless-stopped
-    working_dir: /app
-    volumes:
-      - ./scrobble:/app:ro               # server code (read-only)
-      - novasonic-scrobble-data:/data    # own DB volume, isolated from downloads
-    ports:
-      - "3710:3710"                      # route this port through your reverse proxy
-    environment:
-      - PORT=3710
-      - DATA_PATH=/data
-      - NAVIDROME_URL=${NAVIDROME_URL}   # for ping.view auth verification
-    command: >
-      sh -c "
-        mkdir -p /deps && cd /deps && npm install express &&
-        cd /app && NODE_PATH=/deps/node_modules node --experimental-sqlite scrobble-server.js
-      "
-
-volumes:
-  novasonic-data:          # persistent storage for romaji overrides and app state
-  novasonic-scrobble-data: # persistent play-log DB (novasonic-plays.db)

docker-compose.yml

@@ -1,33 +1,36 @@
-# Default (production) stack — PULLS pre-built images instead of building on the host.
+# NovaSonic — builds locally from the Dockerfiles. The heavy deps (ffmpeg, Deno, yt-dlp, node libs)
+# are baked into the images, so container RESTARTS are instant, and a rebuild after a code change is
+# fast (Docker caches the dep layers — only the code COPY layer changes).
 #
-#   docker compose pull
-#   docker compose up -d
+#   git pull
+#   docker compose up -d --build      # rebuild changed images (cached; fast) and (re)start
+#   docker compose up -d              # just (re)start with the already-built images
 #
-# Build & push the images from your dev machine with:  npm run push-images
-# (see scripts/build-push-images.mjs). Set REGISTRY + TAG in .env (see .env.example).
-# To build on the host instead (dev), use docker-compose.dev.yml.
+# No registry needed. (An optional pull-from-registry / CI flow can build these same Dockerfiles
+# elsewhere and push — see scripts/build-push-images.mjs + .env.example.)
 services:
 
+  # ── Frontend (nginx serving the built PWA) ───────────────────────────────────
   novasonic-frontend:
-    image: ${REGISTRY}/novasonic-frontend:${TAG:-latest}
-    pull_policy: always
+    build: .
     container_name: novasonic-frontend
     restart: unless-stopped
     ports:
-      - "8080:80"
+      - "8080:80"          # route this port through your reverse proxy
     environment:
-      - NAVIDROME_URL=${NAVIDROME_URL}
+      - NAVIDROME_URL=${NAVIDROME_URL}   # pre-filled on the setup screen
       - BACKEND_URL=${BACKEND_URL}
       - SCROBBLE_URL=${SCROBBLE_URL}
 
+  # ── Backend (yt-dlp download server) ─────────────────────────────────────────
   novasonic-backend:
-    image: ${REGISTRY}/novasonic-backend:${TAG:-latest}
-    pull_policy: always
+    build:
+      context: ./backend
     container_name: novasonic-backend
     restart: unless-stopped
     volumes:
       - ${MUSIC_PATH}:${MUSIC_PATH}      # exact path from .env, no remapping
-      - novasonic-data:/data
+      - novasonic-data:/data             # writable data dir for overrides, state, etc.
     ports:
       - "3700:3700"
     environment:
@@ -45,13 +48,14 @@ services:
       - GITEA_TOKEN=${GITEA_TOKEN:-}
       - GITEA_APK_TAG=${GITEA_APK_TAG:-apk-latest}
 
+  # ── Scrobble service (isolated timestamped play-log → stats + Wrapped) ────────
   novasonic-scrobble:
-    image: ${REGISTRY}/novasonic-scrobble:${TAG:-latest}
-    pull_policy: always
+    build:
+      context: ./scrobble
     container_name: novasonic-scrobble
     restart: unless-stopped
     volumes:
-      - novasonic-scrobble-data:/data
+      - novasonic-scrobble-data:/data    # own DB volume, isolated from downloads
     ports:
       - "3710:3710"
     environment: