Deploying Kyoo

Introduction

Kyoo is a modern, open source media browser designed for organizing and streaming your video content. Built with a focus on user experience and performance, Kyoo automatically fetches metadata, artwork, and subtitles for your movies and TV shows, presenting them in a beautiful, Netflix-like interface.

Unlike traditional media servers, Kyoo emphasizes a clean, modern design with features like watch progress tracking, transcoding, and multi-user support. The application is built with .NET on the backend and provides a responsive web interface that works across devices.

Key features of Kyoo:

• Automatic Metadata: Fetches movie and TV show information from TheMovieDB
• Beautiful Interface: Modern, responsive design inspired by streaming services
• Watch Progress: Track where you left off across devices
• Transcoding: Real-time video transcoding for compatibility
• Subtitle Support: Automatic subtitle fetching and embedded subtitle display
• Multi-User Support: Create accounts for family members
• Continue Watching: Resume playback from any device
• Collections: Organize movies into collections
• Search: Quick search across your entire library
• Mobile-Friendly: Responsive design for mobile browsers
• API Access: REST API for third-party integrations
• Open Source: Self-hosted with full data control

This guide walks through deploying Kyoo on Klutch.sh using Docker, configuring your media library, and setting up the streaming interface.

Why Deploy Kyoo on Klutch.sh

Deploying Kyoo on Klutch.sh provides several advantages for media streaming:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kyoo without complex orchestration.

Persistent Storage: Attach persistent volumes for your media library and database. Your collection survives container restarts.

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

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

Scalable Resources: Allocate CPU and memory for transcoding based on your streaming needs.

Environment Variable Management: Securely store API keys and configuration.

Custom Domains: Assign a custom domain for your personal streaming service.

Always-On Availability: Stream your content 24/7 from anywhere.

Prerequisites

Before deploying Kyoo 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
• Your media files organized in a consistent folder structure
• A TheMovieDB API key for metadata fetching
• (Optional) A custom domain for your Kyoo instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Kyoo on Klutch.sh.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/zoriya/kyoo:latest

# Set environment variables
ENV KYOO_DATADIR=/data
ENV KYOO_LIBRARYROOT=/media

# Create directories
RUN mkdir -p /data /media

# Expose the web interface port
EXPOSE 5000

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Default	Description
KYOO_DATADIR	No	/data	Database and cache directory
KYOO_LIBRARYROOT	No	/media	Root directory for media files
KYOO_TMDB_APIKEY	Yes	-	TheMovieDB API key
KYOO_OIDC_ENABLED	No	false	Enable OpenID Connect auth
KYOO_OIDC_CLIENT_ID	No	-	OIDC client ID
KYOO_OIDC_CLIENT_SECRET	No	-	OIDC client secret
KYOO_OIDC_AUTHORITY	No	-	OIDC provider URL
KYOO_REQUIRE_ACCOUNT	No	true	Require login to access

Deploying Kyoo on Klutch.sh

Get a TMDB API Key

1. Create an account at TheMovieDB
2. Go to Settings > API
3. Request an API key
4. Copy your API key (v3 auth)

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Kyoo deployment configuration"
git remote add origin https://github.com/yourusername/kyoo-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 “kyoo” or “media-browser”.

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 Kyoo Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
KYOO_TMDB_APIKEY	Your TheMovieDB API key
KYOO_DATADIR	/data
KYOO_LIBRARYROOT	/media

Attach Persistent Volumes

Add volumes for data persistence:

Mount Path	Recommended Size	Purpose
/data	10 GB	Database and metadata cache
/media	500+ GB	Your media library files

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 Kyoo container
• Provision an HTTPS certificate

Access Kyoo

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

Initial Configuration

First-Time Setup

When you first access Kyoo:

1. Create your admin account
2. Configure your library paths
3. Start the initial library scan
4. Wait for metadata to download

Adding Your Media Library

To add your media:

1. Go to Settings > Libraries
2. Add a new library
3. Select the media type (Movies or Shows)
4. Point to your media directory
5. Start scanning

Media File Organization

For best metadata matching, organize your files:

Movies:

/media/movies/
├── Movie Name (2023)/
│   └── Movie Name (2023).mkv
└── Another Movie (2022)/
    └── Another Movie (2022).mp4

TV Shows:

/media/shows/
├── Show Name/
│   ├── Season 01/
│   │   ├── Show Name - S01E01 - Episode Title.mkv
│   │   └── Show Name - S01E02 - Episode Title.mkv
│   └── Season 02/
│       └── Show Name - S02E01 - Episode Title.mkv

User Management

Creating User Accounts

Set up accounts for family members:

1. Go to Settings > Users
2. Click Add User
3. Set username and password
4. Configure permissions

User Permissions

Permission	Description
Admin	Full access to settings and libraries
User	Can watch and manage own profile
Guest	Limited viewing access

Troubleshooting Common Issues

Metadata Not Loading

• Verify TMDB API key is correct
• Check file naming matches TMDB entries
• Manually match unrecognized items

Playback Issues

• Check video codec compatibility
• Enable transcoding for problematic files
• Verify sufficient CPU for real-time transcoding

Library Scan Slow

• Large libraries take time on initial scan
• Metadata fetching is rate-limited by TMDB
• Consider splitting into multiple libraries

Additional Resources

• Kyoo GitHub Repository
• TheMovieDB API Documentation

Conclusion

Deploying Kyoo on Klutch.sh gives you a beautiful, modern media streaming platform with automatic builds and secure HTTPS access. Enjoy your movie and TV collection with a Netflix-like experience you fully control.