{"id":25941875,"url":"https://github.com/fingerthief/recommendarr","last_synced_at":"2025-05-15T17:07:41.298Z","repository":{"id":280065870,"uuid":"940885683","full_name":"fingerthief/recommendarr","owner":"fingerthief","description":"An LLM driven recommendation system based on Radarr and Sonarr library or watch history information","archived":false,"fork":false,"pushed_at":"2025-04-07T00:40:33.000Z","size":4021,"stargazers_count":605,"open_issues_count":22,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-11T23:58:24.601Z","etag":null,"topics":["ai","artificial-intelligence","jellyfin","local","local-llm-integration","radarr","recommendation","self-hosted","sonarr","tautulli","trakt","vue","vuejs"],"latest_commit_sha":null,"homepage":"","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fingerthief.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-01T01:37:53.000Z","updated_at":"2025-04-11T12:47:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"e1110918-727f-4322-8f9b-6e3e4dc73136","html_url":"https://github.com/fingerthief/recommendarr","commit_stats":null,"previous_names":["fingerthief/recommendarr"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerthief%2Frecommendarr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerthief%2Frecommendarr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerthief%2Frecommendarr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fingerthief%2Frecommendarr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fingerthief","download_url":"https://codeload.github.com/fingerthief/recommendarr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","jellyfin","local","local-llm-integration","radarr","recommendation","self-hosted","sonarr","tautulli","trakt","vue","vuejs"],"created_at":"2025-03-04T06:15:52.258Z","updated_at":"2025-05-15T17:07:36.287Z","avatar_url":"https://github.com/fingerthief.png","language":"Vue","funding_links":[],"categories":["Vue","vue","Complimenting Apps"],"sub_categories":[],"readme":"# Recommendarr\n\n![image](https://github.com/user-attachments/assets/19d332af-f90d-4b6d-8750-4be07bc45161)\n\nRecommendarr is a web application that generates personalized TV show and movie recommendations based on your Sonarr, Radarr, Plex, and Jellyfin libraries using AI.\n\n## [🎮 Join our Discord Community!](https://discord.gg/uHy3KFbgPR)\n\n\u003e **⚠️ IMPORTANT**: When accessing this application from outside your network, you must open the application port on your router/firewall (default: 3000).\n\n\u003e **⚠️ PORT CONFIGURATION**: The application now uses a single port (default: 3000) for both the frontend and API, configurable via the `PORT` environment variable.\n\n## 🌟 Features\n\n- **AI-Powered Recommendations**: Get personalized TV show and movie suggestions based on your existing library\n- **Sonarr \u0026 Radarr Integration**: Connects directly to your media servers to analyze your TV and movie collections\n- **Plex, Jellyfin, Tautulli \u0026 Trakt Integration**: Analyzes your watch history to provide better recommendations based on what you've actually watched\n- **Flexible AI Support**: Works with OpenAI, local models (Ollama/LM Studio), or any OpenAI-compatible API\n- **Customization Options**: Adjust recommendation count, model parameters, and more\n- **Dark/Light Mode**: Toggle between themes based on your preference\n- **Poster Images**: Displays media posters with fallback generation\n\n## 📋 Prerequisites\n\n- [Sonarr](https://sonarr.tv/) instance with API access (for TV recommendations)\n- [Radarr](https://radarr.video/) instance with API access (for movie recommendations)\n- [Plex](https://www.plex.tv/), [Jellyfin](https://jellyfin.org/), [Tautulli](https://tautulli.com/), or [Trakt](https://trakt.tv/) instance with API access (for watch history analysis) - optional\n- An OpenAI API key or any OpenAI-compatible API (like local LLM servers)\n- Docker (recommended) or Node.js (v14+) for manual installation\n\n## 🚀 Quick Start\n\n### Option 1: Docker Hub Image (Easiest)\n\nThe simplest way to get started with Recommendarr:\n\n```bash\n# Pull and run with default port 3000\ndocker run -d \\\n  --name recommendarr \\\n  -p 3000:3000 \\\n  -v recommendarr-data:/app/server/data \\\n  tannermiddleton/recommendarr:latest\n\n# Or run with a custom port (e.g., 8080)\ndocker run -d \\\n  --name recommendarr \\\n  -e PORT=8080 \\\n  -p 8080:8080 \\\n  -v recommendarr-data:/app/server/data \\\n  tannermiddleton/recommendarr:latest\n```\n\nThen visit `http://localhost:3000` (or your custom port) in your browser.\n\n**Default Login:** \n- Username: `admin`\n- Password: `1234`\n\n\u003e **⚠️ IMPORTANT**: Please change your password immediately after your first login for security reasons.\n\n### Option 2: Docker Compose\n\nIf you prefer using Docker Compose:\n\n```bash\n# Clone the repository (which includes the docker-compose.yml file)\ngit clone https://github.com/fingerthief/recommendarr.git\ncd recommendarr\n\n# Start the application\ndocker-compose up -d\n```\n\nThis will:\n1. Pull the pre-built image from Docker Hub\n2. Configure proper networking and persistence\n3. Start the unified service\n\nThen visit `http://localhost:3000` (or your custom port if configured) in your browser.\n\nYou can customize the port by setting the PORT environment variable before running docker-compose:\n\n```bash\nPORT=8080 docker-compose up -d\n```\n\n### Option 3: Build Your Own Docker Image\n\nIf you want to build the Docker image yourself:\n\n```bash\n# Clone the repository\ngit clone https://github.com/fingerthief/recommendarr.git\ncd recommendarr\n\n# Build the Docker image\ndocker build -t recommendarr:local .\n\n# Run the container with default port\ndocker run -d \\\n  --name recommendarr \\\n  -p 3000:3000 \\\n  -v recommendarr-data:/app/server/data \\\n  recommendarr:local\n\n# Or run with custom port\ndocker run -d \\\n  --name recommendarr \\\n  -e PORT=8080 \\\n  -p 8080:8080 \\\n  -v recommendarr-data:/app/server/data \\\n  recommendarr:local\n```\n\n### Option 4: Manual Installation\n\nFor development or if you prefer not to use Docker:\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/fingerthief/recommendarr.git\ncd recommendarr\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the frontend:\n```bash\nnpm run build\n```\n\n4. Start the unified server:\n```bash\nnpm run unified\n```\n\n5. Visit `http://localhost:3000` (or your custom port if configured) in your browser.\n\n## 🔧 Configuration\n\n### 1. Connect to Sonarr, Radarr, and/or Plex/Jellyfin/Trakt\n\n1. When you first open Recommendarr, you'll be prompted to connect to your services\n2. For Sonarr (TV shows):\n   - Enter your Sonarr URL (e.g., `http://localhost:8989` or `https://sonarr.yourdomain.com`)\n   - Enter your Sonarr API key (found in Sonarr under Settings → General)\n   - Click \"Connect\"\n3. For Radarr (Movies):\n   - Enter your Radarr URL (e.g., `http://localhost:7878` or `https://radarr.yourdomain.com`)\n   - Enter your Radarr API key (found in Radarr under Settings → General)\n   - Click \"Connect\"\n4. For Plex (Optional - Watch History):\n   - Enter your Plex URL (e.g., `http://localhost:32400` or `https://plex.yourdomain.com`)\n   - Enter your Plex token (can be found by following [these instructions](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/))\n   - Click \"Connect\"\n5. For Jellyfin (Optional - Watch History):\n   - Enter your Jellyfin URL (e.g., `http://localhost:8096` or `https://jellyfin.yourdomain.com`)\n   - Enter your Jellyfin API key (found in Jellyfin under Dashboard → API Keys)\n   - Enter your Jellyfin user ID (found in Jellyfin user settings)\n   - Click \"Connect\"\n6. For Tautulli (Optional - Watch History):\n   - Enter your Tautulli URL (e.g., `http://localhost:8181` or `https://tautulli.yourdomain.com`)\n   - Enter your Tautulli API key (found in Tautulli under Settings → Web Interface → API)\n   - Click \"Connect\"\n7. For Trakt (Optional - Watch History):\n   - Click \"Connect\" on the Trakt connection page\n   - Authorize Recommendarr with your Trakt.tv account\n   - Complete the authentication process to connect your Trakt watch history\n\nYou can connect to any combination of these services based on your needs.\n\n### 2. Set Up AI Service\n\n1. Navigate to Settings\n2. Select the AI Service tab\n3. Enter your AI service details:\n   - **API URL**: For OpenAI, use `https://api.openai.com/v1`. For local models, use your server URL (e.g., `http://localhost:1234/v1`)\n   - **API Key**: Your OpenAI API key or appropriate key for other services (not needed for some local servers)\n   - **Model**: Select a model from the list or leave as default\n   - **Parameters**: Adjust max tokens and temperature as needed\n4. Click \"Save Settings\"\n\n### 3. Get Recommendations\n\n1. Navigate to TV Recommendations or Movie Recommendations page\n2. Adjust the number of recommendations you'd like to receive using the slider\n3. If connected to Plex, Jellyfin, or Tautulli, choose whether to include your watch history in the recommendations\n4. Click \"Get Recommendations\"\n5. View your personalized media suggestions with posters and descriptions\n\n## 🌐 Setting Up with a Reverse Proxy\n\nIf you want to run Recommendarr behind a reverse proxy (like Nginx, Traefik, or Caddy), follow these steps:\n\n1. Build a custom image with your public URL:\n\n```bash\n# Build with your public URL\ndocker build -t recommendarr:custom \\\n  --build-arg PUBLIC_URL=https://recommendarr.yourdomain.com \\\n  --build-arg BASE_URL=/ \\\n  .\n\n# Run with reverse proxy configuration\ndocker run -d \\\n  --name recommendarr \\\n  -p 3000:3000 \\\n  -e PUBLIC_URL=https://recommendarr.yourdomain.com \\\n  -e FORCE_SECURE_COOKIES=true \\\n  -v recommendarr-data:/app/server/data \\\n  recommendarr:custom\n```\n\n2. Configure your reverse proxy to forward requests to Recommendarr:\n\n**For Nginx:**\n```nginx\nserver {\n    listen 443 ssl;\n    server_name recommendarr.yourdomain.com;\n\n    # SSL configuration\n    ssl_certificate /path/to/cert.pem;\n    ssl_certificate_key /path/to/key.pem;\n\n    location / {\n        proxy_pass http://localhost:3000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n```\n\n**For Docker Compose:**\n\n```yaml\nservices:\n  recommendarr:\n    build:\n      context: .\n      args:\n        - PUBLIC_URL=https://recommendarr.yourdomain.com\n        - BASE_URL=/\n    ports:\n      - \"3000:3000\"\n    # This allows accessing services on the host machine\n    # extra_hosts:\n    #  - \"host.docker.internal:host-gateway\"\n    environment:\n      - NODE_ENV=production\n      - DOCKER_ENV=false\n      - PORT=3000\n      - PUBLIC_URL=https://recommendarr.yourdomain.com\n      # Enable secure cookies when behind HTTPS reverse proxy\n      - FORCE_SECURE_COOKIES=true\n    volumes:\n      - recommendarr-data:/app/server/data\n    restart: unless-stopped\n\nvolumes:\n  recommendarr-data:\n```\n\n## 🔧 Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | The port to run both frontend and API | 3000 |\n| `PUBLIC_URL` | The public URL where the app is accessible | http://localhost:${PORT} |\n| `BASE_URL` | Base path for the application (for sub-path deployment) | / |\n| `FORCE_SECURE_COOKIES` | Force secure cookies even on HTTP (for HTTPS reverse proxies) | false |\n| `NODE_ENV` | Node.js environment | production |\n| `DOCKER_ENV` | Flag to enable Docker-specific features | true |\n\n## 🖥️ Compatible AI Services\n\nRecommendarr works with various AI services:\n\n- **OpenAI API**: Standard integration with models like GPT-3.5 and GPT-4\n- **Ollama**: Self-hosted models with OpenAI-compatible API\n- **LM Studio**: Run models locally on your computer\n- **Anthropic Claude**: Via OpenAI-compatible endpoints\n- **Self-hosted models**: Any service with OpenAI-compatible chat completions API\n\n### Recommended Models\n\nHere are some recommendations for models that work well with Recommendarr:\n\n#### Free/Low-Cost Options via OpenRouter\n- **Meta Llama 3.3 70B Instruct**: Great performance for free\n- **Gemini 2.0 models** (Flash/Pro/Thinking): Excellent recommendation quality\n- **DeepSeek R1 models**: Strong performance across variants\n\n#### Premium Models (Affordable via OpenRouter)\n- **Claude 3.7/3.5 Haiku**: Exceptional for understanding your library preferences\n- **GPT-4o mini**: Excellent balance of performance and cost\n- **Grok Beta**: Good recommendations at reasonable prices\n- **Amazon Nova Pro**: Strong media understanding capabilities\n\n#### Local Models\n- **DeepSeek R1 7B Qwen Distill**: Good performance for a smaller model (via LM Studio)\n\nFor best results, try setting max tokens to 4000 and temperature between 0.6-0.8 depending on the model.\n\n## 🔧 Troubleshooting\n\n### Cookie Errors with Reverse Proxy\n\nIf you're using a reverse proxy with HTTPS and get errors like:\n```\ncookie \"auth_token\" has been rejected because a non-https cookie can't be set \"secure\"\n```\n\nThis happens when your reverse proxy terminates HTTPS but forwards the request to the container as HTTP. To fix this:\n\n1. Add the `FORCE_SECURE_COOKIES=true` environment variable to your docker-compose.yml or docker run command:\n```yaml\nenvironment:\n  - FORCE_SECURE_COOKIES=true\n```\n\n2. Make sure your reverse proxy forwards the correct headers. For Nginx, add:\n```\nproxy_set_header X-Forwarded-Proto $scheme;\n```\n\n### Port Mapping\n\n- Always make sure the internal and external ports match (e.g., 3000:3000)\n- When changing ports, update both the port mapping and PORT environment variable\n\n### Development Setup\n\nFor development purposes, you can run the frontend and backend separately:\n\n```bash\n# Run both frontend and backend in development mode\nnpm run dev\n\n# Or run them separately:\n# Frontend dev server with hot reloading\nnpm run serve\n\n# Backend API server\nnpm run api\n```\n\nThe development server will use port 8080 for the frontend with hot reloading, and port 3050 for the API. In production, both run on a single port.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgements\n\n- [Vue.js](https://vuejs.org/) - The progressive JavaScript framework\n- [Sonarr](https://sonarr.tv/) - For the amazing API that powers TV recommendations\n- [Radarr](https://radarr.video/) - For the API that enables movie recommendations\n- [Plex](https://www.plex.tv/) - For the API that provides watch history data\n- [Jellyfin](https://jellyfin.org/) - For the API that provides additional watch history data\n- [Tautulli](https://tautulli.com/) - For the API that provides detailed Plex watch statistics\n- [Trakt](https://trakt.tv/) - For the API that provides watch history and ratings data\n- [OpenRouter](https://openrouter.ai/docs/quickstart) - For the API that powers AI-based suggestions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffingerthief%2Frecommendarr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffingerthief%2Frecommendarr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffingerthief%2Frecommendarr/lists"}