Deploying nefarious

Introduction

nefarious is a self-hosted web application for automatically downloading movies and TV shows. With a clean, modern interface, nefarious makes it easy to search, request, and manage your media collection while integrating with popular torrent clients and Usenet downloaders.

Built with Django and Vue.js, nefarious provides a responsive experience across devices. It integrates with The Movie Database (TMDB) for rich metadata and supports multiple download backends, making it flexible enough for various media acquisition workflows.

Key highlights of nefarious:

• Movie Management: Search, request, and automatically download movies
• TV Show Support: Track series and automatically download new episodes
• TMDB Integration: Rich metadata, posters, and ratings from The Movie Database
• Multi-Backend Support: Works with Transmission, qBittorrent, and NZBGet
• Jackett Integration: Unified search across multiple torrent indexers
• User Management: Multiple users with different permission levels
• Watch Lists: Track media you want to download
• Quality Profiles: Define preferred resolution and quality settings
• Automatic Renaming: Organize downloads with consistent naming
• Web-Based Interface: Clean Vue.js frontend works on any device
• API Access: REST API for integrations and automation
• Open Source: Licensed under GPL-3.0

This guide walks through deploying nefarious on Klutch.sh using Docker, configuring download clients, and setting up your media management workflow.

Why Deploy nefarious on Klutch.sh

Deploying nefarious on Klutch.sh provides several advantages:

Always-On Management: Your media manager runs 24/7, monitoring for new releases and managing downloads.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds nefarious without complex configuration.

Persistent Storage: Attach persistent volumes for your database, configuration, and media files.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure remote access.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Scalable Resources: Allocate resources based on your media library size and download activity.

Custom Domains: Assign a custom domain for easy access to your media manager.

Prerequisites

Before deploying nefarious on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• A TMDB API key (free at TMDB)
• A download client (Transmission, qBittorrent, or NZBGet)
• (Optional) Jackett for unified torrent searching
• (Optional) A custom domain for your nefarious instance

Understanding nefarious Architecture

nefarious consists of several components:

Django Backend: Handles business logic, database operations, and external API integrations.

Vue.js Frontend: Provides the responsive web interface for searching and managing media.

Celery Workers: Background task processing for downloads, monitoring, and automation.

Redis: Message broker for Celery task queue.

PostgreSQL/SQLite: Database storing media requests, settings, and user data.

Preparing Your Repository

Create a GitHub repository with your nefarious configuration.

Repository Structure

nefarious-deploy/
├── Dockerfile
├── docker-compose.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM lscr.io/linuxserver/nefarious:latest

# Set environment variables
ENV PUID=1000
ENV PGID=1000
ENV TZ=${TZ:-UTC}

# TMDB API configuration
ENV TMDB_API_KEY=${TMDB_API_KEY}

# nefarious configuration
ENV NEFARIOUS_USER=${NEFARIOUS_USER:-admin}
ENV NEFARIOUS_PASS=${NEFARIOUS_PASS}

# Create directories
RUN mkdir -p /config /downloads /movies /tv

# Expose web interface
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8000/ || exit 1

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
TMDB_API_KEY	Yes	-	Your TMDB API key
NEFARIOUS_USER	No	admin	Admin username
NEFARIOUS_PASS	Yes	-	Admin password
TZ	No	UTC	Timezone
PUID	No	1000	User ID for file permissions
PGID	No	1000	Group ID for file permissions

Deploying nefarious on Klutch.sh

Get a TMDB API Key

Register at TMDB and create an API key in your account settings.

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “nefarious”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8000

Set Environment Variables

Configure the following environment variables:

Variable	Value
TMDB_API_KEY	Your TMDB API key
NEFARIOUS_USER	Your admin username
NEFARIOUS_PASS	A strong password
TZ	Your timezone

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/config	5 GB	Configuration and database
/downloads	100+ GB	Temporary download location
/movies	Varies	Completed movies
/tv	Varies	Completed TV shows

Deploy Your Application

Click Deploy to start the build process.

Access nefarious

Once deployment completes, access your instance at https://your-app-name.klutch.sh.

Log In and Configure

Log in with your configured credentials and complete the setup wizard.

Initial Configuration

Setting Up Download Clients

nefarious supports multiple download backends:

Transmission:

1. Go to Settings > Transmission
2. Enter host, port, and credentials
3. Configure download directories

qBittorrent:

1. Go to Settings > qBittorrent
2. Enter host, port, and web UI password
3. Set category and download paths

NZBGet:

1. Go to Settings > NZBGet
2. Enter host, port, and credentials
3. Configure category settings

Configuring Jackett

Jackett provides unified torrent indexer searching:

1. Deploy Jackett (can be on Klutch.sh)
2. Add indexers in Jackett
3. In nefarious, go to Settings > Jackett
4. Enter Jackett URL and API key

Quality Profiles

Define your preferred quality settings:

1. Go to Settings > Quality
2. Set preferred resolution (720p, 1080p, 4K)
3. Configure file size limits
4. Set language preferences

Media Paths

Configure where media is stored:

1. Go to Settings > Paths
2. Set Movies directory: /movies
3. Set TV Shows directory: /tv
4. Configure naming patterns

Managing Media

Searching for Movies

1. Click “Movies” in the sidebar
2. Use the search bar to find movies
3. Click a movie to view details
4. Click “Watch” to add to your library

Managing TV Shows

1. Click “TV” in the sidebar
2. Search for TV shows
3. Select specific seasons or episodes
4. nefarious will monitor for new episodes

Watch Lists

Track media you want to download later:

1. Add movies or shows to your watch list
2. Review and prioritize your list
3. Download when ready

Monitoring Downloads

View active and completed downloads:

1. Go to the Downloads section
2. See progress and status
3. Manage failed downloads

User Management

Creating Additional Users

Share access with family or friends:

1. Go to Settings > Users
2. Create new user accounts
3. Assign appropriate permissions

Permission Levels

Control what users can do:

• Admin: Full access to all features and settings
• User: Can search and request media
• Limited: Can only view, not request

Troubleshooting

Downloads Not Starting

• Verify download client is accessible
• Check download client credentials
• Ensure Jackett indexers are working
• Review nefarious logs for errors

Media Not Found

• Verify TMDB API key is correct
• Check that TMDB is accessible
• Try different search terms

Quality Not Matching

• Review quality profile settings
• Check indexer results for available qualities
• Adjust file size limits

Permission Errors

• Verify PUID and PGID settings
• Check volume mount permissions
• Ensure download directories are writable

Additional Resources

• nefarious GitHub Repository
• TMDB API Documentation
• Jackett GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying nefarious on Klutch.sh gives you a powerful, self-hosted media management solution with a modern web interface. With integration for popular download clients and TMDB metadata, nefarious provides everything needed to automate your media acquisition workflow.

The combination of automatic monitoring, quality profiles, and multi-user support makes nefarious an excellent choice for managing a personal media library. With Klutch.sh’s persistent storage and automatic HTTPS, your media manager remains accessible and secure from anywhere.