Kodi Headless | Media Server | Docker

Kodi Headless: Servidor de media autohospedado sin pantalla en Docker

Centro de medios completo sin necesidad de pantalla. Acceso web noVNC, VNC, API REST. Gestiona películas, series, música, fotos en una interfaz unificada. Base de datos MySQL compartida.

¿Qué es Kodi Headless?

Kodi es un centro de medios open source completo que organiza y reproduce películas, series de TV, música y fotos. "He

adless" significa que corre sin monitor ni teclado/ratón locales. Esta versión con noVNC permite acceder a la interfaz gráfica de Kodi completamente desde un navegador web, perfecta para servidores sin pantalla.

Ventajas: No necesitas una máquina separada "real" de Kodi para configuración. Acceso web desde navegador (noVNC en puerto 8000), VNC tradicional (puerto 5900), API REST (puerto 8080) para controlar desde apps. Soporte para base de datos MySQL compartida entre múltiples dispositivos Kodi. Biblioteca unificada: todas tus películas, series y música sincronizadas.

Centro de medios privado: Sin dependencia de Netflix, Spotify o servicios de streaming. Tu propia biblioteca personal, totalmente controlada, en tu servidor.

Características principales

Web UI (noVNC)

Accede a Kodi desde navegador, no necesitas cliente VNC.

VNC nativo

Acceso tradicional VNC en puerto 5900 para clientes desktop.

API REST

Controla Kodi vía HTTP API desde apps y scripts.

EventServer

Comunicación bidireccional con controles remotos y apps.

Gestión de películas

Organiza, categoriza, busca películas con metadatos.

Series de TV

Gestión de episodios, temporadas, marca visto/no visto.

Servidor de música

Biblioteca de audio con metadatos, radio, podcasts.

Gestor de fotos

Visualiza galerías de fotos organizadas por carpeta.

Base de datos MySQL

Sincroniza biblioteca entre múltiples Kodi.

Add-ons extensibles

Extiende con add-ons: subtítulos, scrapers, skins.

Compatible con todo

Soporta decenas de formatos: MKV, MP4, MKA, MP3, FLAC.

Open Source

GPL. Código auditable, sin dependencias propietarias.

Requisitos del sistema

Docker instalado
MySQL 5.7+ o MariaDB 10.1+ (opcional pero recomendado)
2-4 GB de RAM mínimo
10+ GB de espacio en disco para base de datos y caché
Puertos: 8000 (web noVNC), 5900 (VNC), 8080 (API), 9090 (websockets), 9777/UDP (EventServer)
CPU multi-core recomendado

Base de datos recomendada: Para funcionalidad completa, usa MySQL compartida con otros dispositivos Kodi. SQLite integrado también funciona pero más lento.

Instalación con Docker Compose

Opción 1: Con MySQL compartida

version: '3' services: mysql: image: mysql:8.0 container_name: kodi-mysql restart: unless-stopped environment: - MYSQL_ROOT_PASSWORD=root-pass - MYSQL_DATABASE=kodivideodb110 - MYSQL_USER=kodi - MYSQL_PASSWORD=kodi volumes: - mysql-data:/var/lib/mysql kodi: image: fhriley/kodi-headless-novnc:latest container_name: kodi-headless restart: unless-stopped depends_on: - mysql ports: - "8000:8000" # Web noVNC - "5900:5900" # VNC - "8080:8080" # API HTTP - "9090:9090" # WebSocket - "9777:9777/udp" # EventServer volumes: - ./kodi-data:/data - /mnt/media:/media # Tu librería de medios environment: - KODI_DB_HOST=mysql - KODI_DB_PORT=3306 - KODI_DB_USER=kodi - KODI_DB_PASS=kodi - KODI_DB_NAME=kodivideodb110 - TZ=Europe/Madrid - KODI_UMASK=002 volumes: mysql-data:

Iniciar

docker compose up -d

Acceder a Kodi

Web (noVNC): http://localhost:8000
VNC nativo: localhost:5900 (con cliente VNC)
API REST: http://localhost:8080/jsonrpc

Primeros pasos

1. Acceder a Kodi por primera vez

Abre http://localhost:8000
Verás Kodi ejecutándose sin pantalla, interfaz completa en navegador
Usa mouse/teclado desde el navegador para controlar
El ratón de tu navegador controla el cursor de Kodi

2. Configurar fuentes de medios

Ve a "Settings" → "Media" → "Libraries" → "Videos"
Click "Add videos..."
Selecciona tu ruta de películas (/media si montaste volumen)
Establece tipo de contenido: "Movies" o "TV Shows"
Kodi escanea automáticamente y descarga metadatos

3. Añadir biblioteca de música

Settings → Media → Music
Añade carpeta con archivos de audio
Kodi indexa y crea biblioteca

4. Configurar base de datos MySQL (opcional pero recomendado)

Ya está configurada si usaste docker-compose con MySQL
Ahora puedes tener múltiples Kodi con la misma biblioteca
Cada dispositivo vería la misma colección sincronizada

5. Instalar add-ons

Va a "Add-ons" → "Install from repository"
Navega categorías: Video, Audio, Subtítulos, Skins
Instala lo que necesites (Kodi, TMDb, OpenSubtitles)

Optimización para escaneo rápido

Path substitution (SMB rápido)

Si tu media está en SMB compartido, puedes acelerar el escaneo mapeando a ruta local:

# En advancedsettings.xml dentro de Kodi <pathsubstitution> <substitute> <from>smb://192.168.1.100/media/</from> <to>/media/</to> </substitute> </pathsubstitution>

Montar media como volumen local

docker-compose.yml: volumes: - /mnt/tank/movies:/media # Copia rápida local

Resultado: Escaneo de 1000 películas en segundos en lugar de minutos.

HTTPS con Caddy (acceso remoto)

Configuración Caddyfile

kodi.tudominio.com { reverse_proxy localhost:8000 }

Acceso desde cualquier lugar

Con Caddy + Kodi, puedes acceder a tu biblioteca desde cualquier sitio:

Configura Caddy con dominio
HTTPS automático con Let's Encrypt
Accede: https://kodi.tudominio.com
Interfaz web completa desde navegador

Casos de uso

Centro de medios casero: Película, TV, música, fotos en un lugar
Servidor sin pantalla: En closet o rack sin monitor
Multi-dispositivo: Múltiples Kodi con misma biblioteca vía MySQL
Reproductor web: Accede desde laptop, tablet, teléfono
Reemplazo de Netflix: Tu propia librería privada
Cine en casa: Reproducción a TV via HDMI o streaming
Organización de contenido: Metadatos automáticos, carátulas

Gestión y mantenimiento

Ver logs

docker compose logs -f kodi

Shell en contenedor

docker exec -it kodi-headless bash

Rescan biblioteca (actualizar)

En Kodi: Settings → Media → Libraries → Movies → Scan for new content

Limpiar caché de Kodi

docker exec -it kodi-headless rm -rf /data/.kodi/cache/*

Backup de Kodi config

docker run --rm \ -v kodi-data:/data \ -v $(pwd):/backup \ alpine tar czf /backup/kodi-backup-$(date +%Y%m%d).tar.gz -C /data .

Actualizar a la última versión

docker compose pull docker compose up -d

Reiniciar Kodi

docker compose restart kodi

Referencias oficiales

Apoya el canal GENBYTE

Suscríbete al canal de YouTube Suscríbete a la newsletter semanal Invítame a un Ko-fi genbyte@proton.me

Cómo instalar Kodi en Docker - Servidor de media autohospedado sin pantalla en Docker