AuralStash

AuralStash is a self-hosted music discovery and acquisition controller. The current scaffold includes a FastAPI API, platform-aware discovery and download services, a compact Vite React operations console, an Expo Router mobile app, and a shared generated TypeScript API client.

The MVP keeps all provider actions and filesystem paths on the server. Web and mobile clients talk to the same /api/v1 API.

See TODO.md for the current project status, completed work, and next tasks.

Local Development

Backend tests:

npm run backend:test

Full local verification:

npm run check

Web e2e smoke, including Discover, Saved, Settings, Preferences, Admin, and voice transcription:

npm run check:e2e

Backend API:

npm run backend:dev

Web app:

npm install
npm --workspace frontend run dev

Web e2e:

npm run web:e2e

Mobile app:

npm --workspace mobile run start

Docker:

docker compose up --build

The frontend container runs as AURALSTASH_DOCKER_UID:AURALSTASH_DOCKER_GID to avoid root-owned files in bind-mounted node_modules; the defaults are 1000:1000.

Forgejo can build the Docker images with .forgejo/workflows/docker-image.yml. Configure FORGEJO_REGISTRY_TOKEN with package/container registry write access before expecting pushes; set FORGEJO_REGISTRY_USER only when the token username differs from the workflow actor. Pull requests build only. Pushes to main publish git.step1.ro/stanta/auralstash-api:latest, git.step1.ro/stanta/auralstash-frontend:latest, and sha-<commit> tags for both images, while v* tags also publish the matching version tag.

The production frontend image serves the built Vite app with nginx and proxies /api/ to the API container. Use the frontend container as the browser entrypoint so web requests stay same-origin:

AURALSTASH_POSTGRES_PASSWORD=change-me \
AURALSTASH_CREDENTIAL_ENCRYPTION_KEY=change-me-too \
docker compose -f docker-compose.prod.yml up -d

Production Compose enables API healthchecks, Redis healthchecks, secure session cookies, a conservative per-process API rate limit, and a 20 MiB voice upload cap. Set AURALSTASH_SESSION_COOKIE_SECURE=false only when testing the production stack over plain HTTP. Adjust AURALSTASH_RATE_LIMIT_REQUESTS, AURALSTASH_RATE_LIMIT_WINDOW_SECONDS, and AURALSTASH_VOICE_MAX_UPLOAD_BYTES for your reverse proxy and expected client behavior.

The Forgejo runner job container must have the Docker CLI and access to a Docker daemon. With act_runner, that usually means using a label image that includes the Docker CLI and mounting the host socket, for example /var/run/docker.sock:/var/run/docker.sock, in the runner configuration.

Database-backed auth records, server settings, platform/provider accounts, saved recommendations, download jobs, local file records, LLM usage, and audit events are optional in this scaffold. Set AURALSTASH_STORAGE_BACKEND=database, configure AURALSTASH_DATABASE_URL, then run:

cd backend
../.venv/bin/python -m alembic upgrade head

Queue execution defaults to AURALSTASH_QUEUE_BACKEND=inline, which runs mock provider work in the API process for local development. Docker Compose sets AURALSTASH_QUEUE_BACKEND=celery with database storage so the worker updates durable job records through Redis/Celery.

Provider and platform credentials are scoped to the authenticated AuralStash user and encrypted before they are stored in provider_accounts.encrypted_credentials. Set AURALSTASH_CREDENTIAL_ENCRYPTION_KEY to a stable secret in any database-backed environment; the checked-in default is for local development only. To rotate keys, set the new key first and old keys after it, then re-encrypt existing rows:

cd backend
AURALSTASH_CREDENTIAL_ENCRYPTION_KEY="new-key,old-key" ../.venv/bin/python -m app.tools.rotate_credentials --dry-run
AURALSTASH_CREDENTIAL_ENCRYPTION_KEY="new-key,old-key" ../.venv/bin/python -m app.tools.rotate_credentials

Internal and external users share the same users.id boundary. Future LDAP/OIDC adapters should provision users through AuthService.provision_external_user, so settings and linked platform/provider accounts remain scoped to the same user id.

Admins can create local users, edit roles, disable/enable accounts, reset passwords, and revoke web sessions or device tokens from the web console. Disabled users are rejected during web login, device login, cookie auth, and bearer-token auth.

LLM provider API keys and provider passwords belong in the dedicated credentials fields, never in free-form config. Public admin config, audit, and usage responses recursively redact secret-like field names as a defense in depth, but deployment operators should still treat database backups as sensitive.

MVP Surface

• /api/v1/health
• /api/v1/auth/login/web
• /api/v1/auth/login/device
• /api/v1/auth/me
• /api/v1/auth/logout/web
• /api/v1/discovery
• /api/v1/preferences
• /api/v1/voice/transcribe
• /api/v1/library/scans
• /api/v1/library/summary
• /api/v1/library/search
• /api/v1/recommendations
• /api/v1/queue
• /api/v1/jobs
• /api/v1/downloads
• /api/v1/settings
• /api/v1/providers
• /api/v1/platforms
• /api/v1/admin/*

Qobuz is the first platform adapter. Platform search and downloads use configured account-authorized API paths only; the project does not implement unofficial downloader behavior, app-secret extraction, URL signing, DRM bypass, or paywall bypass behavior.