Deploying Medusa

Introduction

Medusa is an automatic video library manager for TV shows. It watches for new episodes of your favorite shows and when they are released, it finds, downloads, and processes them. Medusa can be configured to automatically download subtitles, rename files according to your preferences, and organize your library structure.

Originally a fork of SickRage and SickBeard, Medusa has evolved into a robust, actively maintained project with a modern web interface and extensive feature set. It integrates with numerous download clients, indexers, and media servers to provide a complete automation solution for TV show management.

Key highlights of Medusa:

• Automatic Episode Tracking: Monitors your shows and downloads new episodes as they air
• Quality Management: Set quality preferences and automatically upgrade to better releases
• Subtitle Downloads: Automatically finds and downloads subtitles in your preferred languages
• Smart Renaming: Rename and organize files according to customizable templates
• Multiple Indexer Support: Works with numerous Usenet and torrent indexers
• Download Client Integration: Supports SABnzbd, NZBGet, Transmission, qBittorrent, Deluge, and more
• Media Server Integration: Notifies Plex, Emby, Kodi, and other media servers of new content
• Failed Download Handling: Automatically retries with alternate releases when downloads fail
• Manual Search: Search for specific episodes when automatic search doesn’t find results
• Modern Web Interface: Clean, responsive interface for managing your library

This guide walks through deploying Medusa on Klutch.sh using Docker, configuring persistent storage, and setting up automatic TV show management.

Why Deploy Medusa on Klutch.sh

Deploying Medusa on Klutch.sh provides several advantages for automated TV library management:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Medusa without complex orchestration. Push to GitHub, and your automation platform deploys automatically.

Persistent Storage: Attach persistent volumes for your configuration and media library. Your shows and settings survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure remote access to your Medusa instance.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your library size and processing needs.

Always-On Availability: Your TV automation runs 24/7 without managing your own hardware.

Custom Domains: Assign a custom domain for easy access to your Medusa dashboard.

Prerequisites

Before deploying Medusa 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
• Access to Usenet or torrent indexers
• A download client (SABnzbd, NZBGet, Transmission, etc.)
• (Optional) A custom domain for your Medusa instance

Preparing Your Repository

To deploy Medusa on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

medusa-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM lscr.io/linuxserver/medusa:latest

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

# Create media directories
RUN mkdir -p /tv /downloads

# Expose the web interface port
EXPOSE 8081

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

Environment Variables Reference

Variable	Required	Default	Description
PUID	No	1000	User ID for file ownership
PGID	No	1000	Group ID for file ownership
TZ	No	Etc/UTC	Timezone for scheduling

Deploying on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Medusa deployment configuration"
git remote add origin https://github.com/yourusername/medusa-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “medusa” or “tv-automation”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Medusa Dockerfile.

Configure HTTP Traffic

Medusa serves its web interface over HTTP. In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
PUID	1000
PGID	1000
TZ	Your timezone (e.g., America/New_York)

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/config	5 GB	Configuration, database, and logs
/tv	500+ GB	TV show library
/downloads	100+ GB	Download staging area

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Medusa container
• Provision an HTTPS certificate

Access Medusa

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

Initial Configuration

First-Time Setup

When you first access Medusa:

1. Navigate to Settings > General
2. Set your preferred language and timezone
3. Configure API key for remote access

Adding Indexers

Configure search providers:

1. Go to Settings > Search Providers
2. Add your Usenet indexers (Newznab-compatible)
3. Add your torrent indexers
4. Set provider priorities

Configuring Download Clients

Set up your download client:

1. Navigate to Settings > Search Settings
2. Configure Usenet client (SABnzbd, NZBGet)
3. Configure Torrent client (Transmission, qBittorrent, Deluge)
4. Test connections

Media Server Integration

Connect to your media server:

1. Go to Settings > Notifications
2. Enable your media server (Plex, Emby, Kodi)
3. Configure connection details
4. Test notifications

Adding Shows

Adding a New Show

1. Click Shows > Add Shows
2. Search for your show by name
3. Select the correct result from TVDB/TMDB
4. Choose quality settings
5. Select root folder for storage
6. Set initial episode status

Quality Settings

Configure quality preferences:

• Initial: Quality for new downloads
• Archive: Quality for older episodes
• Preferred: Trigger upgrades to this quality
• Allowed: All acceptable quality levels

Episode Status

Set how Medusa handles existing episodes:

• Wanted: Download episodes
• Skipped: Ignore episodes
• Ignored: Never download
• Archived: Already have in best quality

Automation Features

Automatic Searches

Medusa runs searches automatically:

• Daily Search: Looks for episodes that aired recently
• Backlog Search: Finds missing older episodes
• Proper Search: Finds corrected releases

Post-Processing

Configure what happens after downloads:

1. Go to Settings > Post Processing
2. Enable automatic post-processing
3. Set renaming pattern
4. Configure file operations (move, copy, link)

Subtitle Downloads

Enable automatic subtitle downloads:

1. Go to Settings > Subtitles
2. Enable subtitle downloads
3. Select preferred languages
4. Choose subtitle services (OpenSubtitles, Addic7ed, etc.)

File Organization

Renaming Patterns

Customize file naming with patterns:

# Example patterns
%SN - S%0SE%0E - %EN           # Show Name - S01E01 - Episode Name
%S.N.S%0SE%0E.%EN              # Show.Name.S01E01.Episode.Name
%SN/Season %S/%SN - S%0SE%0E   # Organized in folders

Available Variables

Variable	Description
%SN	Show Name
%S.N	Show Name (with dots)
%S	Season Number
%0S	Season Number (zero-padded)
%E	Episode Number
%0E	Episode Number (zero-padded)
%EN	Episode Name
%Y	Year
%Q	Quality

Security

Authentication

Protect your Medusa instance:

1. Go to Settings > General
2. Set username and password
3. Enable authentication

API Security

For API access:

1. Generate a secure API key
2. Use the API key for remote access
3. Limit API access to trusted applications

Troubleshooting

Shows Not Downloading

• Verify indexers are configured correctly
• Check download client connection
• Review logs for search errors
• Ensure shows are set to “Wanted” status

Post-Processing Failing

• Check file permissions
• Verify destination path exists
• Review naming pattern syntax
• Check available disk space

Subtitles Not Found

• Enable multiple subtitle providers
• Check provider credentials
• Verify show naming is correct for matches

Additional Resources

• Medusa GitHub Repository
• Medusa Wiki
• Medusa Discord
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Medusa on Klutch.sh gives you a powerful, automated TV show management system that runs 24/7. With extensive indexer support, download client integration, and media server notifications, Medusa automates the entire process of finding, downloading, and organizing your TV library.

The combination of Medusa’s feature-rich automation and Klutch.sh’s reliable infrastructure means you can build and maintain a well-organized TV collection without manual intervention. Simply add your shows, configure your preferences, and let Medusa handle the rest.