Instalación Koel · 12 min read · Nov 03, 2025

Cómo instalar el servidor de transmisión de música Koel usando Docker en Rocky Linux 8

Koel es un servicio de transmisión de audio basado en la web escrito en el marco PHP Laravel. Te permite transmitir tu colección personal de música y acceder a ella desde cualquier lugar del mundo. Soporta múltiples formatos de medios, incluyendo AAC, OGG, WMA, FLAC y APE.

En este tutorial, aprenderás cómo instalar el servidor de transmisión de música Koel usando Docker en una máquina Rocky Linux 8.

Prerrequisitos

  • Un servidor ejecutando Rocky Linux 8.5.
  • Un usuario no root con privilegios sudo.
  • Actualiza todo. $ sudo dnf update
  • Instala paquetes esenciales. $ sudo dnf install yum-utils nano curl
  • Un nombre de dominio personalizado apuntando al servidor como koel.example.com.

Paso 1 - Configurar el Firewall

El primer paso es configurar el firewall. Rocky Linux utiliza Firewalld Firewall. Verifica el estado del firewall.

$ sudo firewall-cmd --state
running

El firewall trabaja con diferentes zonas, y la zona pública es la predeterminada que utilizaremos. Lista todos los servicios y puertos activos en el firewall.

$ sudo firewall-cmd --permanent --list-services

Debería mostrar la siguiente salida.

cockpit dhcpv6-client ssh

Permite los puertos HTTP y HTTPS.

$ sudo firewall-cmd --permanent --add-service=http
$ sudo firewall-cmd --permanent --add-service=https

Revisa nuevamente el estado del firewall.

$ sudo firewall-cmd --permanent --list-services

Deberías ver una salida similar.

cockpit dhcpv6-client http https ssh

Recarga el firewall para habilitar los cambios.

$ sudo firewall-cmd --reload

Paso 2 - Instalar Docker

Rocky Linux viene con una versión más antigua de Docker. Para instalar la última versión, primero, instala el repositorio oficial de Docker.

$ sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo

Instala la última versión de Docker.

$ sudo dnf install docker-ce docker-ce-cli containerd.io

Habilita y ejecuta el daemon de Docker.

$ sudo systemctl enable docker --now

Verifica que esté corriendo.

? docker.service - Docker Application Container Engine
   Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; vendor preset: disabled)
   Active: active (running) since Sat 2022-04-02 13:26:08 UTC; 2s ago
     Docs: https://docs.docker.com
 Main PID: 21152 (dockerd)
    Tasks: 7
   Memory: 30.9M
   CGroup: /system.slice/docker.service
           ??21152 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
...

Por defecto, Docker requiere privilegios de root. Si deseas evitar usar sudo cada vez que ejecutes el comando docker, agrega tu nombre de usuario al grupo docker.

$ sudo usermod -aG docker $(whoami)

Necesitarás cerrar sesión en el servidor y volver a iniciar sesión como el mismo usuario para habilitar este cambio.

Paso 3 - Instalar Docker Compose

Descarga la última versión estable de Docker Compose.

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Aplica permisos ejecutables al archivo binario de Docker Compose.

$ sudo chmod +x /usr/local/bin/docker-compose

Prueba la instalación.

$ docker-compose --version
docker-compose version 1.29.2, build 5becea4c

Instala el script de finalización de Bash de Docker-compose.

$ sudo curl \
    -L https://raw.githubusercontent.com/docker/compose/1.29.2/contrib/completion/bash/docker-compose \
    -o /etc/bash_completion.d/docker-compose

Recarga la configuración de tu perfil para que la finalización de bash funcione.

$ source ~/.bashrc

Paso 4 - Crear la clave de la aplicación Koel

Generaremos la clave de la aplicación de Koel ejecutando el contenedor por un corto momento. Ejecuta el siguiente comando para correr el contenedor y acceder a su shell.

$ docker run -it --rm phanan/koel bash

Una vez dentro del contenedor, ejecuta el siguiente comando para generar la clave de la aplicación.

$ php artisan key:generate --force

Salida del archivo de entorno modificado con la nueva clave de aplicación generada.

$ cat .env
APP_KEY=base64:fjtO7aVHHKWfk4DThKqf1nci6o2DuMkNd90TKX6Gj+4=

Copia el valor de la clave y sal del shell del contenedor.

$ exit

Paso 5 - Crear el archivo de entorno de Koel

Crea un directorio para Koel.

$ mkdir ~/koel

Cambia al directorio.

$ cd ~/koel

Crea el directorio de música.

$ mkdir music

Crea y abre el archivo .env.

$ nano .env

Pega el siguiente código en él.

APP_NAME=Koel

# Una cadena aleatoria de 32 caracteres. Puedes dejar esto vacío si usas php artisan koel:init.
APP_KEY=base64:fjtO7aVHHKWfk4DThKqf1nci6o2DuMkNd90TKX6Gj+4=

# La ruta ABSOLUTA a tus medios. Este valor siempre se puede cambiar más tarde a través de la interfaz web.
MEDIA_PATH=/music

APP_ENV=production
APP_DEBUG=true
APP_URL=https://koel.example.com

# El tiempo máximo de escaneo, en segundos. Aumenta esto si tienes una biblioteca enorme.
# Nota: Esta configuración no tiene efecto al escanear a través de koel:sync.
APP_MAX_SCAN_TIME=600

# El límite de memoria, en MB, utilizado por el proceso de escaneo.
# Por ejemplo, si deseas establecer un límite de memoria de 2048MB, ingresa "2048" (sin
# comillas) aquí.
MEMORY_LIMIT=512

# El método de transmisión.
# Puede ser 'php' (predeterminado), 'x-sendfile' o 'x-accel-redirect'
# Consulta https://docs.koel.dev/#streaming-music para más información.
# Nota: Esta configuración no tiene efecto si los medios necesitan transcodificación (por ejemplo, FLAC).
STREAMING_METHOD=x-sendfile

# Si deseas que Koel se integre con Last.fm, establece los detalles de la API aquí.
# Consulta https://docs.koel.dev/3rd-party.html#last-fm para más información
LASTFM_API_KEY=
LASTFM_API_SECRET=

# Si deseas usar Amazon S3 con Koel, completa la información aquí y sigue la
# guía de instalación en https://docs.koel.dev/aws-s3.html
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=

# Si deseas que Koel se integre con YouTube, establece la clave de API aquí.
# Consulta https://docs.koel.dev/3rd-party.html#youtube para más información.
YOUTUBE_API_KEY=

# También puedes configurar Koel para usar un CDN para servir los archivos multimedia.
# Esta URL debe estar mapeada a la URL de inicio de tu instalación de Koel.
# Sin barra diagonal al final, por favor.
CDN_URL=

# La tasa de bits de la transmisión de salida mp3. Un valor más alto resulta en mejor calidad,
# pero transmisión más lenta y más ancho de banda.
OUTPUT_BIT_RATE=128

# Si permitir descargar canciones.
# Nota que si descargas más de una canción, Koel las comprimirá
# usando ZipArchive de PHP. Así que si el módulo no está disponible en el entorno actual,
# dicha descarga fallará (silenciosamente).
ALLOW_DOWNLOAD=true

# Si esto se establece en verdadero, la consulta para obtener información de artista, álbum y canción se almacenará en caché.
# Esto puede dar un impulso al tiempo de arranque de Koel, especialmente si tu biblioteca es enorme.
# Sin embargo, el proceso de deserialización de caché puede ser sensible a la memoria, así que si encuentras
# errores, intenta establecer esto en falso.
CACHE_MEDIA=true

# Koel intenta detectar si tu sitio web usa HTTPS y genera URLs seguras en consecuencia.
# Si esto falla por alguna razón, puedes forzarlo estableciendo este valor en verdadero.
FORCE_HTTPS=true

# Las variables a continuación son específicas de Laravel.
# Puedes cambiarlas si sabes lo que estás haciendo. De lo contrario, déjalas como están.
APP_LOG_LEVEL=debug
BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_DRIVER=sync

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

La mayoría de las configuraciones son autoexplicativas arriba. Las siguientes configuraciones necesitan ser configuradas para que funcione. Pega la clave de la aplicación generada en el paso anterior contra la variable APP_KEY. Ingresa tu nombre de dominio bajo APP_URL, y establece el límite de memoria en MB dependiendo de los recursos de tu servidor. Hemos establecido el método de transmisión a x-sendfile ya que la imagen de Docker de Koel utiliza Apache y viene preconfigurada con él. La configuración FORCE_HTTPS se establece en verdadero porque usaremos Nginx como un balanceador de carga junto con Let’s Encrypt SSL para servir Koel en la web. Configura otros servicios si deseas usarlos junto con Koel.

Paso 6 - Crear el archivo Docker Compose de Koel

Crea y abre el archivo docker-compose.yml para editar.

$ nano docker-compose.yml

Pega el siguiente código en él.

version: '3.3'

services:
  koel:
    image: phanan/koel
    container_name: koel
    depends_on:
      - koeldb
    restart: unless-stopped
    ports:
      - 8080:80
    environment:
      - DB_CONNECTION=mysql
      - DB_HOST=koeldb
      - DB_USERNAME=koel
      - DB_PASSWORD=koelpassword
      - DB_DATABASE=koel
    volumes:
      - ./music:/music
      - ./.env:/var/www/html/.env
      - covers:/var/www/html/public/img/covers
      - search_index:/var/www/html/storage/search-indexes

  koeldb:
    image: mysql/mysql-server:8.0
    restart: unless-stopped
    volumes:
      - db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=koel
      - MYSQL_USER=koel
      - MYSQL_PASSWORD=koelpassword

volumes:
  db:
    driver: local
  covers:
    driver: local
  search_index:
    driver: local

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

El archivo anterior lanza contenedores basados en las imágenes de Docker de Koel y MySQL. Expone Koel al puerto 8080 en tu máquina. La música y el archivo de entorno se montan en las ubicaciones respectivas en el contenedor. El directorio para las portadas de música y el índice de búsqueda, junto con los datos de MySQL, se montan como volúmenes locales. Elige una contraseña fuerte para las variables MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD y haz que esos valores coincidan con las variables para el contenedor de Koel en el archivo anterior. Para vincular el contenedor de Koel con el contenedor de base de datos, asegúrate de que las variables DB_HOST y depends_on estén nombradas según el nombre del servicio del contenedor de base de datos.

Paso 7 - Iniciar el contenedor de Koel

Lanza el contenedor de Koel usando el siguiente comando.

$ docker-compose up -d

Inicializar Koel por primera vez

Inicia sesión en el shell del contenedor de Koel. koel en el comando a continuación se refiere al nombre del contenedor establecido a través de la variable container_name en el archivo Docker compose anterior. Si no tienes un nombre de contenedor establecido, tendrás que encontrar el nombre del contenedor primero y usar eso en el siguiente comando.

$ docker exec --user www-data -it koel bash

Ejecuta el siguiente comando para crear una cuenta de administrador e inicializar la base de datos.

$ php artisan koel:init --no-assets

Cambiar la contraseña del administrador

Koel crea una cuenta de administrador predeterminada con las siguientes credenciales.

email: [email protected]
password: KoelIsCool

Puedes cambiar la contraseña de la cuenta de administrador usando el siguiente comando desde dentro del shell del contenedor.

$ php artisan koel:admin:change-password

Sal del shell del contenedor.

$ exit

Paso 8 - Instalar SSL

Para instalar un certificado SSL usando Let’s Encrypt, necesitamos instalar la herramienta Certbot.

Primero, necesitas descargar e instalar el repositorio EPEL.

$ sudo dnf install epel-release

Ejecuta los siguientes comandos para instalar Certbot.

$ sudo dnf install certbot

Genera el certificado SSL.

$ sudo certbot certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d koel.example.com

El comando anterior descargará un certificado en el directorio /etc/letsencrypt/live/koel.example.com en tu servidor.

Genera un certificado de grupo Diffie-Hellman.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096

Crea un directorio raíz de desafío web para la renovación automática de Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Crea un trabajo Cron para renovar el SSL. Se ejecutará todos los días para verificar el certificado y renovarlo si es necesario. Para eso, primero, crea el archivo /etc/cron.daily/certbot-renew y ábrelo para editar.

$ sudo nano /etc/cron.daily/certbot-renew

Pega el siguiente código.

#!/bin/sh
certbot renew --cert-name koel.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

Cambia los permisos en el archivo de tarea para hacerlo ejecutable.

$ sudo chmod +x /etc/cron.daily/certbot-renew

Paso 9 - Instalar Nginx

Instalaremos la última versión de Nginx. Crea y abre el archivo /etc/yum.repos.d/nginx.repo para editar.

$ sudo nano /etc/yum.repos.d/nginx.repo

Pega las siguientes líneas en él.

[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

Instala Nginx.

$ sudo dnf install nginx

Verifica la instalación.

$ nginx -v
nginx version: nginx/1.20.2

Habilita e inicia el servicio de Nginx.

$ sudo systemctl enable nginx --now

Crea y abre el archivo /etc/nginx/conf.d/koel.conf para editar.

$ sudo nano /etc/nginx/conf.d/koel.conf

Pega el siguiente código en él.

# Redirigir todo lo no encriptado a encriptado
server {
    listen 80;
    listen [::]:80;
    server_name koel.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    
    server_name koel.example.com;

    ssl_certificate     /etc/letsencrypt/live/koel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/koel.example.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/koel.example.com/chain.pem;
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

    access_log /var/log/nginx/koel.example.com.access.log main;
    error_log  /var/log/nginx/koel.example.com.error.log;

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Host $host;
        client_max_body_size 400M;
     proxy_pass  http://localhost:8080;
     proxy_http_version 1.1;
        proxy_set_header Host $host;
    }
}

Una vez terminado, guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida. La configuración anterior permite que Nginx actúe como un servidor proxy y se vincule al puerto 8080 en localhost.

Abre el archivo /etc/nginx/nginx.conf para editar.

$ sudo nano /etc/nginx/nginx.conf

Agrega la siguiente línea antes de la línea include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Guarda el archivo presionando Ctrl + X y entrando Y cuando se te pida.

Verifica la sintaxis del archivo de configuración de Nginx.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Reinicia el servicio de Nginx para habilitar la nueva configuración.

$ sudo systemctl restart nginx

Paso 10 - Acceder a Koel

Puedes acceder a Koel visitando la URL https://koel.example.com en tu navegador. Serás recibido por la siguiente pantalla de inicio de sesión.

Pantalla de inicio de sesión de Koel

Ingresa [email protected] como tu nombre de usuario y la contraseña que configuraste antes de iniciar sesión. El siguiente panel aparecerá al iniciar sesión con éxito.

Panel de control de Koel

Paso 11 - Importar música

Copia los archivos de música que deseas importar a la carpeta ~/koel/music de tu sistema. Puedes usar el comando scp para importar los archivos desde tu PC local al servidor.

$ scp test.mp3 user@:/home/user/koel/music

Una vez que hayas copiado los archivos a la carpeta ~/koel/music, ejecuta el siguiente comando para importar la música a Koel.

$ docker exec --user www-data koel php artisan koel:sync

La música aparecerá en la interfaz web de Koel, y podrás comenzar a reproducirla.

La interfaz web de Koel también te permite subir canciones directamente.

Paso 12 - Actualizar Koel

Cambia al directorio de Koel.

$ cd ~/koel

Descarga la última imagen de Docker de Koel.

$ docker-compose pull

Apaga el contenedor.

$ docker-compose down --remove-orphans

Inicia el contenedor con las imágenes actualizadas.

$ docker-compose up -d

Verifica los contenedores de Docker.

$ docker ps

Conclusión

Esto concluye el tutorial sobre la instalación del servicio de transmisión de música Koel usando Docker en un servidor Rocky Linux. Si tienes alguna pregunta, publícalas en los comentarios a continuación.

Share: X/Twitter LinkedIn
#Instalación Koel

Recibe nuevas publicaciones en tu bandeja de entrada.

No spam. Cancela la suscripción en cualquier momento.