muzick/AGENTS.md

Muzick — Agent Context

music player + recommendation engine. muzick.kvmx.ru:5174.

ports

• 5174:80 — frontend (docker)
• 3000:3000 — backend api (docker, internal)

docker-compose services

• db — postgres 16, schema at backend/src/db/schema.sql
• redis — redis 7, job queue
• search — typesense 0.25.1 (pinned), full-text search
• backend — fastify/typescript, music dir mount at /music
• frontend — vite SPA, served by nginx inside container
• worker — metadata enrichment (lastfm, discogs, musicbrainz), network_mode: host

env (.env)

• LASTFM_API_KEY, LASTFM_SHARED_SECRET
• MUSICBRAINZ_CONTACT
• DISCOGS_TOKEN
• SOCKS_PROXY_URL=socks5://192.168.1.104:10808 — for external api calls

gotchas

• worker uses network_mode: host + SOCKS5 proxy for metadata lookups.
• typesense is pinned to 0.25.1 — not latest. don't bump casually, the api changes between major versions.
• db schema is in backend/src/db/schema.sql — dropped in via docker-entrypoint-initdb.d.
• music dir is read-only bind from /mnt/hdd1/media/Music.
• there's also an older muzick.service systemd unit that runs the backend solo on port 5213 — that's the pre-docker version and may conflict. the docker compose is the active deployment.