Melodarr - Self-hosted Music Discovery for Lidarr

Self-hosted music discovery, album requests, and Lidarr automation with optional Jellyfin login.

Repository · Container Image · Releases · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Project Links
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Environment Variables
3. Usage
4. Development
5. Roadmap
6. Contributing
7. License

About The Project

Melodarr is a self-hosted music discovery and request app for Lidarr. It gives homelab and media-server users a friendlier way to search MusicBrainz-backed Lidarr results, find artists, albums, and singles, and submit music requests that can be reviewed, approved, and automatically added to Lidarr.

Melodarr is inspired by Seerr, but focused on music libraries. Jellyfin can optionally be used for shared login, so household users can sign in with existing Jellyfin credentials instead of creating separate Melodarr-only accounts.

Key features:

• First-run setup wizard with admin account creation
• Browse and discover artists, albums, and singles via Lidarr-backed discovery
• Search by artist, release, or song title to find matching albums and singles
• Request albums or full artist discographies, then submit them to Lidarr
• Request status tracking from review to Lidarr submission through completed imports
• Submitted-request sync that checks Lidarr availability before marking requests complete
• Safer proxied artwork loading with cover fallbacks from public music metadata sources
• Optional admin approval flow or auto-approve mode
• Optional Jellyfin login alongside local accounts
• Admin settings panel for Lidarr, Jellyfin, and request configuration
• Rate limiting and audit logging
• Persistent PostgreSQL and Redis storage

(back to top)

Project Links

Resource	Link
Source code	github.com/oxon1um/melodarr
Container image	ghcr.io/oxon1um/melodarr
Releases	GitHub Releases
Issues and feature requests	GitHub Issues

Common use cases include Lidarr music requests, self-hosted music discovery, Jellyfin-backed household access, MusicBrainz-powered search, and Docker-based homelab deployments.

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

The recommended deployment path is Docker Compose, which starts Melodarr, PostgreSQL, and Redis together.

Prerequisites

• Docker with Docker Compose
• A secure session secret

  openssl rand -hex 64

• A running Lidarr instance for submitting music requests
• Optional, but recommended: a running Jellyfin instance for shared user login

Installation

1. Clone the repo

   git clone https://github.com/oxon1um/melodarr.git
   cd melodarr

2. Create a .env file and set SESSION_SECRET

   SESSION_SECRET=your-generated-session-secret

3. Start the Docker Compose stack

   docker compose up -d

   The included Compose file pins the Melodarr image to v0.1.0-alpha3. Update the image tag when upgrading to a newer release.

   Docker startup runs checked-in Prisma migrations with prisma migrate deploy. New installs start from an empty database and apply the bundled initial migration automatically.

4. Open Melodarr

   http://localhost:30000

5. Complete the first-run setup wizard, then configure Lidarr and optional Jellyfin login from Settings.

Environment Variables

Variable	Default	Description
SESSION_SECRET	-	Required. Generate with openssl rand -hex 64
DATABASE_URL	postgresql://melodarr:melodarr@db:5432/melodarr?schema=public	PostgreSQL connection string
REDIS_URL	redis://redis:6379	Redis connection string
POSTGRES_USER	melodarr	Database username for Docker Compose
POSTGRES_PASSWORD	melodarr	Database password for Docker Compose
POSTGRES_DB	melodarr	Database name for Docker Compose
APP_URL	-	Application URL for OAuth and cookies
JELLYFIN_URL	-	Optional Jellyfin server URL for shared user login
JELLYFIN_API_KEY	-	Optional Jellyfin API key for shared user login
LIDARR_URL	-	Lidarr server URL
LIDARR_API_KEY	-	Lidarr API key
LIDARR_ROOT_FOLDER	-	Default Lidarr root folder path
LIDARR_QUALITY_PROFILE_ID	-	Default Lidarr quality profile ID
LIDARR_METADATA_PROFILE_ID	-	Default Lidarr metadata profile ID
LIDARR_MONITOR_MODE	all	Default Lidarr monitor mode
REQUEST_AUTO_APPROVE	true	Automatically approve new requests

Additional Lidarr, optional Jellyfin login, and request settings can be configured in the admin panel or through environment variables. See .env.example for local development defaults.

(back to top)

Usage

After the first-run setup wizard:

1. Create the initial admin account.
2. Go to Settings and configure the Lidarr connection.
3. Optionally configure Jellyfin login so users can sign in with existing Jellyfin credentials.
4. Browse discovered artists, albums, and singles. Song-title searches return the matching album or single release when Lidarr provides enough metadata.
5. Request albums or full artist discographies.
6. Track each request until Lidarr reports the requested album is available.

Request statuses:

Status	Description
PENDING	Waiting for admin review when approval is required
APPROVED	Approved and ready to submit to Lidarr
SUBMITTED	Sent to Lidarr and waiting for the album to become fully available
COMPLETED	Lidarr reports the requested album is fully available in the library
FAILED	Request could not be completed
REJECTED	Request was declined
ALREADY_EXISTS	Requested media already exists

Default Docker port mapping:

Host	Container
30000	3000

TrueNAS Scale

1. Create a dataset for persistent storage, such as /mnt/pool/apps/melodarr/.
2. In TrueNAS Apps, select Custom App.
3. Set the required environment variables.
4. Map /mnt/pool/apps/melodarr/postgres to /var/lib/postgresql for PostgreSQL.
5. Map /mnt/pool/apps/melodarr/redis to /data for Redis.

Upgrading existing alpha installs

Melodarr uses Prisma migrations at container startup. If you ran an early alpha build that created tables with prisma db push before migrations were added, the first upgrade can fail with Prisma P3005 because the existing database is not empty and has no migration history yet.

This is a one-time baseline step for those existing databases only. New empty deployments do not need it.

Run this against the same Docker network and database credentials used by your Melodarr stack, then restart the app container:

docker run --rm \
  --network <melodarr-network> \
  --entrypoint npx \
  -e DATABASE_URL='postgresql://melodarr:melodarr@db:5432/melodarr?schema=public' \
  ghcr.io/oxon1um/melodarr:v0.1.0-alpha3 \
  prisma migrate resolve --applied 20260428100000_init

On systems that require elevated Docker access, prefix the command with sudo. Replace the network, username, password, host, and database name if your deployment does not use the Compose defaults.

(back to top)

Development

Use Node.js 20 for local development, CI, and Docker builds.

1. Install dependencies

   nvm use
   npm install

2. Start local PostgreSQL and Redis services

   docker compose -f docker-compose.local.yml up -d db redis

3. Create .env.local

   cp .env.example .env.local

4. Generate Prisma client

   npm run prisma:generate

5. Start the development server

   npm run dev

Useful commands:

Command	Description
npm run dev	Start the Next.js development server
npm run build	Create a production build
npm run start	Serve the production build on port 3000
npm run lint	Run ESLint
npm run test	Run the Vitest suite
npm run test:e2e	Run Playwright end-to-end tests
npm run verify	Run the project verification script
npm run prisma:generate	Generate Prisma client
npm run prisma:push	Push schema changes to the database
npm run prisma:migrate	Apply Prisma migrations

Docker startup applies checked-in Prisma migrations with prisma migrate deploy before starting the app.

For request status sync and discover-home freshness, make sure your local app can reach the same Lidarr instance configured in Melodarr settings.

(back to top)

Roadmap

See the open issues for proposed features and known issues.

(back to top)

Contributing

Contributions are welcome.

1. Fork the project.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'feat: add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a pull request.

Before opening a pull request, run:

npm run verify

See Development Workflow for the required branch, pull request, and verification-gate process.

(back to top)

License

Distributed under the MIT License. See LICENSE for details.

(back to top)