AI-powered song generation platform. Create albums and songs with lyrics + style prompts, generate music via ACE-Step, auto-master to MP3, and score quality.
SvelteKit frontend + FastAPI backend + PostgreSQL + Redis + arq job workers + GPU ACE-Step worker.
Songmaker is Docker-only — there is no native local-dev path. The Docker stack runs the web app, both arq workers, the ACE-Step GPU worker, PostgreSQL, Redis, Prometheus, and Grafana.
Requires: Docker (with Compose v2), NVIDIA Container Toolkit (for GPU generation), and a Hugging Face token (for downloading ACE-Step model weights).
# 1. First-time setup
cp docker/.env.docker.example .env # edit with your secrets — see file for required fields
docker compose up -d --build --wait
# Cold-cache rebuild takes 8-15 min the first time. Never wrap in `timeout`
# (see CLAUDE.md "Docker" section for the full reasoning).
# 2. Install the agent-CLI login mirror (one-time, needs sudo)
sudo ./scripts/install-cli-credentials-mirror.sh
# 3. Install the boot autostart unit (one-time, needs sudo)
sudo ./scripts/install-autostart.shrestart: unless-stopped alone does not survive every reboot: a container that
was created but never started (e.g. a mid-boot GPU driver mismatch) is never
retried by Docker on its own, no matter how many times the host reboots.
scripts/install-autostart.sh installs a systemd unit that runs
docker compose up -d after every boot, which does retry it — see
docs/acestep.md.
The first start downloads ~3.5 GB of ACE-Step model weights into the songmaker_hfcache Docker volume (one-time). All persistent state (PostgreSQL DB, audio files, model cache, Grafana dashboards) lives in named Docker volumes and survives docker compose down and --build rebuilds.
# Update after pulling new code
git pull && docker compose up -d --build --wait
# View logs (one service at a time)
docker compose logs -f songmaker-web # API + frontend
docker compose logs -f songmaker-music-worker # generation jobs (arq)
docker compose logs -f songmaker-scoring-worker # scoring jobs (arq)
docker compose logs -f songmaker-acestep-worker-0 # GPU subprocess (ACE-Step)
# Container status
docker compose ps -a # all services + health (-a: includes a Created-but-never-started container, which plain `ps` hides)
# Stop / start the stack (preserves volumes)
docker compose stop
docker compose start
# Cloudflare tunnel (if you've set one up for remote access)
sudo systemctl start cloudflared
sudo systemctl stop cloudflared
sudo systemctl status cloudflaredThese are the four secrets that must be set or Settings will raise ValidationError at startup:
| Var | Purpose |
|---|---|
SESSION_SECRET |
HMAC signing key for session cookies (min 32 chars) |
POSTGRES_PASSWORD |
PostgreSQL password (substituted into the postgres container env) |
SONGMAKER_INTERNAL_TOKEN |
Shared secret for worker → web internal API auth |
HF_TOKEN |
Hugging Face token for downloading ACE-Step + scoring model weights |
Generate secrets with python3 -c "import secrets; print(secrets.token_hex(32))". See docker/.env.docker.example for the full list including all optional overrides.
The local Python .venv exists for tests, type checking, and IDE autocomplete only — not for running the live app. The live app always runs in Docker.
# One-time setup
uv sync --extra server --extra scoring --extra whisper --extra mcp --extra image --extra dev
# Run the test suite
pytest tests/ -n auto -q
# Run the linter
ruff check src/ tests/
# Frontend tests / lint / type-check
cd frontend && pnpm install && pnpm test:coverage && pnpm lint && pnpm check && pnpm buildTests run against an in-memory SQLite database (no Postgres needed for unit tests) and fakeredis. The live Docker stack and the test suite are fully independent — you can run tests while the Docker stack is up.
The auth layer and the provider layer are external dependencies:
overnightworks-webauth and overnightworks-agent-providers are each pinned in
the server extra to the release wheel of tag v0.1.0 of
overnightworks/webauth and
overnightworks/agent-providers
and hash-locked in uv.lock, so uv sync installs them like any other
dependency and their own tests run in those repositories.
Both PostgreSQL and the audio files Docker volume must be backed up together. See scripts/BACKUP.md for the setup, cron, and restore instructions. The default BACKUP_DIR is /mnt/backup/songmaker but can be overridden via env var.
BACKUP_DIR=/path/to/backup ./scripts/backup.sh- CLAUDE.md — project conventions, code patterns, and "Known Technical Debt." Read this first if you're contributing.
- docs/VISION.md — non-normative product overview and pointer to approved intent
- docs/requirements/ — normative requirement grammar and revision registry
- docs/PRODUCT.md — generated requirement/acceptance count view; no implementation claim yet
- docs/architecture.md — system design, data model, API endpoints, worker pool, monitoring, backup
- docs/security.md — auth, sessions, CSRF, rate limiting, security headers, trust boundaries
- docs/testing.md — test structure, fixtures, coverage targets
- docs/acestep.md — ACE-Step integration, model variants, worker pool, generation parameters
- plans/ — design plans for in-flight and proposed work. Each has a
**Status:**header. - overnightworks/webauth — the extracted auth library songmaker installs by tag
- overnightworks/agent-providers — the extracted provider library songmaker installs by tag
MIT