Cómo instalar Kumiho en Docker: Servidor de medios ultraligero para manga y cómics
Kumiho | Media Server | Golang
Kumiho: Servidor de medios ultraligero para manga y cómics
Gestiona y transmite tu colección personal de manga, cómics y novelas con un servidor web rápido, ligero y autohospedado construido con Golang.
Aspecto de la aplicación
¿Qué es Kumiho?
Kumiho (구미호) es un servidor de medios web autohospedado diseñado específicamente para gestionar y transmitir colecciones personales de manga, cómics, webtoons y novelas. Desarrollado originalmente por un usuario insatisfecho con las soluciones existentes, Kumiho prioriza la velocidad, la simplicidad y el bajo consumo de recursos.
Construido completamente en Golang, Kumiho se ejecuta como un binario nativo sin la sobrecarga de JVM o entornos de ejecución pesados. Esto lo hace ideal para dispositivos NAS de bajos recursos, Raspberry Pi, o cualquier servidor donde la eficiencia sea importante.
Filosofía de diseño: Sin bases de datos complejas, sin gestión de metadatos complicada. Kumiho simplemente refleja tu estructura de carpetas tal como está, mostrando tu biblioteca exactamente como la organizaste en tu sistema de archivos.
Características principales
| Característica | Descripción |
|---|---|
| Velocidad abrumadora | Binario nativo Golang sin sobrecarga de JVM. Escaneo de biblioteca extremadamente rápido. |
| Espejo del sistema de archivos | Tu estructura de carpetas se muestra directamente en la interfaz (Tree View). Sin metadatos complejos. |
| Recursos mínimos | Funciona perfectamente en NAS de bajos recursos con huella de memoria mínima. |
| Visor web responsive | Streaming sin interrupciones en PC, tablets y móviles. Soporte para modo Webtoon (scroll vertical). |
| BGM inmersivo | Reproduce automáticamente archivos MP3 con el mismo nombre que la serie durante la lectura. |
| Sin dependencias externas | Todo en un solo binario. Sin necesidad de instalar dependencias separadas. |
Formatos soportados
Actualmente soportados
| Categoría | Extensiones |
|---|---|
| Imágenes | .jpg, .jpeg, .png, .webp, .gif, .bmp |
| Archivos comprimidos | .zip, .cbz |
Próximamente
.cbr (RAR)
.rar
.cb7 (7-Zip)
.7z
.epub
.pdf
.txt
Funciones planificadas
- comicInfo.xml: Soporte completo para metadatos de cómics
- OPDS: Protocolo para integración con apps de lectura móviles
Estructura de carpetas: Kumiho reconoce automáticamente carpetas con imágenes o archivos comprimidos y los organiza en volúmenes/capítulos.
Instalación con Docker
Método 1: Docker Compose (recomendado)
Paso 1: Crear el directorio del proyecto
mkdir ~/kumiho
cd ~/kumiho
Paso 2: Crear docker-compose.yml
version: "3.8"
services:
kumiho:
image: ahahyeong/kumiho:latest
container_name: kumiho
restart: unless-stopped
ports:
- "9999:9999" # Puerto externo:Puerto interno
volumes:
- ./data:/app/data # Base de datos y datos (obligatorio)
- ./config:/app/config # Configuración (opcional)
- ./books:/books # Ruta de tu biblioteca de libros
environment:
- PUID=1000 # User ID (verifica con comando 'id')
- PGID=1000 # Group ID
- TZ=Europe/Madrid
- JWT_SECRET=tu-secreto-seguro-aqui # Clave secreta para seguridad
Importante sobre v0.9.0: Esta versión cambió los permisos del contenedor de
root a usuario estándar (appuser). Si actualizas desde versiones anteriores y ves miniaturas rotas o errores "Permission Denied", debes configurar PUID y PGID con tu ID de usuario (verifica con el comando id en terminal).
Paso 3: Iniciar el contenedor
docker compose up -d
Paso 4: Verificar el estado
# Ver logs
docker compose logs -f kumiho
# Comprobar estado
docker compose ps
Método 2: Docker Run
docker run -d \
--name kumiho \
-p 9999:9999 \
-v $(pwd)/data:/app/data \
-v $(pwd)/config:/app/config \
-v $(pwd)/books:/books \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Europe/Madrid \
-e JWT_SECRET=tu-secreto-seguro-aqui \
--restart unless-stopped \
ahahyeong/kumiho:latest
Acceder a Kumiho
Abre tu navegador y ve a: http://localhost:9999
Configuración de la biblioteca
Configurar la ruta de la biblioteca
Este paso es crucial y frecuentemente causa confusión:
- Accede a Kumiho en
http://localhost:9999 - Ve a Settings → Libraries
- Haz clic en Add New Library
- En el campo Set Path, introduce:
/books
Atención: Si montaste
./books:/books en tu Docker Compose, debes usar la ruta del contenedor /books en la configuración, NO la ruta del host ./books.
Estructura de carpetas recomendada
books/
├── Manga/
│ ├── One Piece/
│ │ ├── Volume 01/
│ │ │ ├── 001.jpg
│ │ │ ├── 002.jpg
│ │ │ └── ...
│ │ ├── Volume 02/
│ │ └── ...
│ └── Attack on Titan/
├── Comics/
│ └── Batman/
└── Webtoons/
└── Tower of God/
Características especiales
Reproducción automática de BGM
Kumiho puede reproducir música de fondo automáticamente durante la lectura:
- Coloca un archivo MP3 en la carpeta de la serie
- Nombra el archivo exactamente igual que el archivo de la serie
- El audio se reproducirá automáticamente al abrir ese volumen/capítulo
Ejemplo:
One Piece/
├── Volume 01.cbz
├── Volume 01.mp3 ← Se reproduce al abrir Volume 01.cbz
├── Volume 02.cbz
└── Volume 02.mp3 ← Se reproduce al abrir Volume 02.cbz
Modo Webtoon
Para manga o cómics de scroll vertical (estilo webtoon), Kumiho ofrece un modo de lectura especializado que permite desplazamiento continuo en lugar de navegación página por página.
Variables de entorno
| Variable | Descripción | Valor por defecto |
|---|---|---|
| PUID | User ID del sistema. Verifica con id |
1000 |
| PGID | Group ID del sistema. Verifica con id |
1000 |
| TZ | Zona horaria del contenedor | Asia/Seoul |
| JWT_SECRET | Clave secreta para tokens de autenticación (recomendado) | — |
Seguridad: Genera un
JWT_SECRET fuerte con: openssl rand -hex 32
Gestión del contenedor
Ver logs en tiempo real
docker compose logs -f kumiho
Reiniciar el servicio
docker compose restart kumiho
Detener Kumiho
docker compose down
Actualizar a la última versión
docker compose pull
docker compose up -d
Verificar permisos (si hay problemas con miniaturas)
# Verificar tu UID y GID
id
# Ajustar permisos de las carpetas (reemplaza 1000 con tu UID/GID)
sudo chown -R 1000:1000 ./data ./config ./books
Stack tecnológico
- Backend: Golang 1.21+
- Frontend: React + Vite + TypeScript
- Autenticación: JWT
- Base de datos: SQLite (integrada)
- Licencia: Apache 2.0
Casos de uso
- Biblioteca personal de manga: Organiza y lee tu colección completa desde cualquier dispositivo
- Servidor familiar: Comparte tu biblioteca con familia sin servicios cloud de terceros
- Webtoon reader: Lee webtoons con modo de scroll continuo optimizado
- Cómics occidentales: Gestiona colecciones de DC, Marvel, Image Comics, etc.
- NAS ligero: Servidor de medios eficiente para dispositivos con recursos limitados
- Novelas visuales: Lee novelas ligeras con imágenes en formato cómodo
Comentarios
Publicar un comentario