Deploying Kodi Headless

Introduction

Kodi is an award-winning free and open-source media player and entertainment hub for digital media. While Kodi is traditionally a desktop application, the Kodi Headless server allows you to run a centralized Kodi instance that manages a shared library database, enabling multiple Kodi clients to share the same library, watch status, and metadata.

The headless version runs without a display, making it perfect for server deployments. Combined with a MySQL/MariaDB database, multiple Kodi clients can sync their libraries, ensuring that when you mark a show as watched on your living room TV, it shows as watched everywhere else too.

Key highlights of Kodi Headless:

• Centralized Library: Single library database shared across all clients
• Watch Status Sync: Watched/unwatched status syncs across devices
• Library Updates: Central point for library scanning and updates
• Web Interface: Manage Kodi through a web browser
• JSON-RPC API: Full API for automation and third-party apps
• Efficient Scanning: Scan media once, not on every client
• Reduced Bandwidth: Metadata stored centrally, not duplicated
• Client Agnostic: Works with any Kodi installation
• Add-on Support: Install and manage add-ons remotely
• Lightweight: Runs without GPU or display requirements

This guide walks through deploying Kodi Headless on Klutch.sh using Docker, configuring MySQL for library sharing, and setting up client synchronization.

Why Deploy Kodi Headless on Klutch.sh

Deploying Kodi Headless on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Kodi Headless from your Dockerfile.

Persistent Storage: Store your Kodi configuration and userdata persistently.

Remote Access: Access the web interface from anywhere for library management.

Always-On Library: Library scanning and updates happen even when clients are off.

Central Management: Manage your media library without running a full Kodi client.

Prerequisites

Before deploying Kodi Headless on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A MySQL or MariaDB database for shared library
• Media files accessible via network paths (NFS, SMB)
• Basic familiarity with Docker and Kodi

Preparing Your Repository

To deploy Kodi Headless on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

kodi-headless-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM lscr.io/linuxserver/kodi-headless:latest

# Environment variables
ENV PUID=1000
ENV PGID=1000
ENV TZ=Etc/UTC

# Volumes:
# /config/.kodi - Kodi configuration and userdata

# Ports:
# 8080 - Web interface
# 9090 - JSON-RPC/WebSocket
# 9777/udp - EventServer

EXPOSE 8080 9090 9777/udp

Environment Variables Reference

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

Creating the .dockerignore File

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

Deploying Kodi Headless on Klutch.sh

Set Up MySQL Database

Kodi’s shared library requires MySQL/MariaDB:

• Use a managed database service
• Deploy MariaDB on Klutch.sh

Create databases for your libraries:

CREATE DATABASE kodi_video;
CREATE DATABASE kodi_music;
CREATE USER 'kodi'@'%' IDENTIFIED BY 'secure_password';
GRANT ALL ON kodi_video.* TO 'kodi'@'%';
GRANT ALL ON kodi_music.* TO 'kodi'@'%';

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Kodi Headless deployment configuration"
git remote add origin https://github.com/yourusername/kodi-headless-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 “kodi” or “media-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Kodi Headless repository.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

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

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/config/.kodi	2 GB	Kodi userdata and configuration

Deploy Your Application

Click Deploy to start the build process.

Access Kodi

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

Default credentials: kodi / kodi

Configuring MySQL Library Sharing

Creating advancedsettings.xml

Create this file in your Kodi userdata to enable MySQL:

<advancedsettings>
  <videodatabase>
    <type>mysql</type>
    <host>your-mysql-host</host>
    <port>3306</port>
    <user>kodi</user>
    <pass>secure_password</pass>
    <name>kodi_video</name>
  </videodatabase>
  <musicdatabase>
    <type>mysql</type>
    <host>your-mysql-host</host>
    <port>3306</port>
    <user>kodi</user>
    <pass>secure_password</pass>
    <name>kodi_music</name>
  </musicdatabase>
  <videolibrary>
    <importwatchedstate>true</importwatchedstate>
    <importresumepoint>true</importresumepoint>
  </videolibrary>
</advancedsettings>

Deploying the Configuration

1. Create advancedsettings.xml with your database settings
2. Place it in the persistent volume at /config/.kodi/userdata/
3. Restart the container

Web Interface

Accessing the Web UI

Navigate to https://your-app-name.klutch.sh to access Kodi’s web interface.

Web Interface Features

• Library Browsing: View movies, TV shows, and music
• Now Playing: Control playback on connected clients
• Remote Control: Send commands to Kodi clients
• File Browser: Navigate media sources
• Add-on Management: Install and configure add-ons

Changing Default Credentials

1. Access the web interface
2. Navigate to Settings > Web Server
3. Update username and password
4. Save and restart

Client Configuration

Configuring Kodi Clients

Each Kodi client needs the same advancedsettings.xml:

1. Copy the same MySQL configuration to each client
2. Configure identical media sources using network paths
3. Library will sync automatically

Media Source Paths

Important: Use identical network paths on all devices:

<!-- Good: Network path, works everywhere -->
<source>
  <path>smb://server/media/movies/</path>
</source>

<!-- Bad: Local path, only works on one device -->
<source>
  <path>/mnt/media/movies/</path>
</source>

API Access

JSON-RPC API

Kodi provides a powerful API for automation:

List movies:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"VideoLibrary.GetMovies","id":1}' \
  https://your-app-name.klutch.sh/jsonrpc

Scan library:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"VideoLibrary.Scan","id":1}' \
  https://your-app-name.klutch.sh/jsonrpc

Integration with Other Tools

Kodi’s API integrates with:

• Radarr/Sonarr: Trigger library updates on new downloads
• Home Assistant: Automation and control
• Kore: Official Kodi remote app

Production Best Practices

Library Management

• Scheduled Scans: Set up periodic library scans
• Source Monitoring: Enable source monitoring for automatic updates
• Clean Library: Periodically clean removed media from library

Database Maintenance

• Regular Backups: Back up MySQL databases
• Optimize Tables: Periodically optimize large tables
• Monitor Size: Large libraries can grow significantly

Security

• Change Defaults: Update default kodi/kodi credentials
• Secure Database: Use strong MySQL passwords
• Network Security: Restrict database access appropriately

Troubleshooting Common Issues

Library Not Syncing

Solutions:

• Verify MySQL connection settings
• Check advancedsettings.xml on all devices
• Ensure identical source paths across devices
• Review MySQL user permissions

Web Interface Not Loading

Solutions:

• Verify port 8080 is configured correctly
• Check application logs for errors
• Ensure web server is enabled in settings

Slow Library Scans

Solutions:

• Check network connectivity to media sources
• Optimize media source paths
• Consider faster database server

Additional Resources

• Kodi Website
• Kodi Wiki
• LinuxServer Kodi Headless
• Kodi MySQL Setup
• Klutch.sh Deployments

Conclusion

Deploying Kodi Headless on Klutch.sh gives you a centralized media library server with automatic builds and persistent storage. The combination of Kodi’s powerful media management and Klutch.sh’s deployment simplicity means you can maintain a synchronized media library across all your devices without running a full media center on a server.

Whether managing a home theater setup or providing a shared library for multiple locations, Kodi Headless on Klutch.sh provides the foundation for a unified media experience.