Instalação Koel · 12 min read · Nov 03, 2025

Como Instalar o Servidor de Streaming de Música Koel Usando Docker no Rocky Linux 8

Koel é um serviço de streaming de áudio baseado na web escrito no framework PHP Laravel. Ele permite que você transmita sua coleção pessoal de músicas e a acesse de qualquer lugar do mundo. Suporta vários formatos de mídia, incluindo AAC, OGG, WMA, FLAC e APE.

Neste tutorial, você aprenderá como instalar o Servidor de Streaming de Música Koel usando Docker em uma máquina Rocky Linux 8.

Pré-requisitos

  • Um servidor rodando Rocky Linux 8.5.
  • Um usuário não-root com privilégios sudo.
  • Atualize tudo. $ sudo dnf update
  • Instale pacotes essenciais. $ sudo dnf install yum-utils nano curl
  • Um nome de domínio personalizado apontando para o servidor como koel.example.com.

Passo 1 - Configurar o Firewall

O primeiro passo é configurar o firewall. O Rocky Linux usa o Firewalld Firewall. Verifique o status do firewall.

$ sudo firewall-cmd --state
running

O firewall funciona com diferentes zonas, e a zona pública é a padrão que usaremos. Liste todos os serviços e portas ativos no firewall.

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

Deve mostrar a seguinte saída.

cockpit dhcpv6-client ssh

Permita as portas HTTP e HTTPS.

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

Verifique novamente o status do firewall.

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

Você deve ver uma saída semelhante.

cockpit dhcpv6-client http https ssh

Recarregue o firewall para habilitar as mudanças.

$ sudo firewall-cmd --reload

Passo 2 - Instalar o Docker

O Rocky Linux vem com uma versão mais antiga do Docker. Para instalar a versão mais recente, primeiro, instale o repositório oficial do Docker.

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

Instale a versão mais recente do Docker.

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

Habilite e execute o daemon do Docker.

$ sudo systemctl enable docker --now

Verifique se está rodando.

? 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 padrão, o Docker requer privilégios de root. Se você quiser evitar usar sudo toda vez que executar o comando docker, adicione seu nome de usuário ao grupo docker.

$ sudo usermod -aG docker $(whoami)

Você precisará sair do servidor e entrar novamente como o mesmo usuário para habilitar essa mudança.

Passo 3 - Instalar o Docker Compose

Baixe a versão estável mais recente do 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

Aplique permissões executáveis ao arquivo binário do Docker Compose.

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

Teste a instalação.

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

Instale o script de conclusão do Bash do 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

Recarregue suas configurações de perfil para fazer a conclusão do bash funcionar.

$ source ~/.bashrc

Passo 4 - Criar a Chave do App Koel

Geraremos a chave do App Koel executando o contêiner por um curto momento. Execute o seguinte comando para rodar o contêiner e acessar seu shell.

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

Uma vez dentro do contêiner, execute o seguinte comando para gerar a chave do aplicativo.

$ php artisan key:generate --force

Saída do arquivo de ambiente modificado com a nova chave do app gerada.

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

Copie o valor da chave e saia do shell do contêiner.

$ exit

Passo 5 - Criar o Arquivo de Ambiente do Koel

Crie um diretório para o Koel.

$ mkdir ~/koel

Mude para o diretório.

$ cd ~/koel

Crie o diretório de música.

$ mkdir music

Crie e abra o arquivo .env.

$ nano .env

Cole o seguinte código nele.

APP_NAME=Koel

# Uma string aleatória de 32 caracteres. Você pode deixar isso vazio se usar php artisan koel:init.
APP_KEY=base64:fjtO7aVHHKWfk4DThKqf1nci6o2DuMkNd90TKX6Gj+4=

# O caminho ABSOLUTO para sua mídia. Este valor pode sempre ser alterado mais tarde via interface web.
MEDIA_PATH=/music

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

# O tempo máximo de varredura, em segundos. Aumente isso se você tiver uma biblioteca enorme.
# Nota: Esta configuração não tem efeito ao escanear via koel:sync.
APP_MAX_SCAN_TIME=600

# O limite de memória, em MB, usado pelo processo de varredura.
# Por exemplo, se você quiser definir um limite de memória de 2048MB, insira "2048" (sem
# aspas) aqui.
MEMORY_LIMIT=512

# O método de streaming.
# Pode ser 'php' (padrão), 'x-sendfile' ou 'x-accel-redirect'
# Veja https://docs.koel.dev/#streaming-music para mais informações.
# Nota: Esta configuração não tem efeito se a mídia precisar de transcodificação (por exemplo, FLAC).
STREAMING_METHOD=x-sendfile

# Se você quiser que o Koel integre com Last.fm, defina os detalhes da API aqui.
# Veja https://docs.koel.dev/3rd-party.html#last-fm para mais informações
LASTFM_API_KEY=
LASTFM_API_SECRET=

# Se você quiser usar o Amazon S3 com o Koel, preencha as informações aqui e siga o
# guia de instalação em https://docs.koel.dev/aws-s3.html
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=

# Se você quiser que o Koel integre com o YouTube, defina a chave da API aqui.
# Veja https://docs.koel.dev/3rd-party.html#youtube para mais informações.
YOUTUBE_API_KEY=

# Você também pode configurar o Koel para usar um CDN para servir os arquivos de mídia.
# Esta URL deve ser mapeada para a URL inicial da instalação do Koel.
# Sem barra no final, por favor.
CDN_URL=

# A taxa de bits do stream mp3 de saída. Um valor mais alto resulta em melhor qualidade,
# mas streaming mais lento e mais largura de banda.
OUTPUT_BIT_RATE=128

# Se deve permitir o download de músicas.
# Nota que se você estiver baixando mais de uma música, o Koel irá compactá-las
# usando o ZipArchive do PHP. Portanto, se o módulo não estiver disponível no ambiente atual,
# tal download falhará (silenciosamente).
ALLOW_DOWNLOAD=true

# Se isso estiver definido como verdadeiro, a consulta para obter informações sobre artista, álbum e música será armazenada em cache.
# Isso pode dar um impulso ao tempo de inicialização do Koel, especialmente se sua biblioteca for enorme.
# No entanto, o processo de desserialização do cache pode ser sensível à memória, então se você encontrar
# erros, tente definir isso como falso.
CACHE_MEDIA=true

# O Koel tenta detectar se seu site usa HTTPS e gera URLs seguras de acordo.
# Se isso falhar por qualquer motivo, você pode forçar isso definindo este valor como verdadeiro.
FORCE_HTTPS=true

# As variáveis abaixo são específicas do Laravel.
# Você pode alterá-las se souber o que está fazendo. Caso contrário, apenas deixe-as como estão.
APP_LOG_LEVEL=debug
BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_DRIVER=sync

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

A maioria das configurações é autoexplicativa acima. As seguintes configurações precisam ser configuradas para que funcione. Cole a chave do app gerada na etapa anterior contra a variável APP_KEY. Insira seu nome de domínio sob APP_URL e defina o limite de memória em MB dependendo dos recursos do seu servidor. Definimos o método de streaming como x-sendfile, pois a imagem do docker do Koel usa o Apache e vem pré-configurada com ele. A configuração FORCE_HTTPS está definida como verdadeira porque usaremos o Nginx como um balanceador de carga junto com o SSL Let’s Encrypt para servir o Koel na web. Configure outros serviços se quiser usá-los junto com o Koel.

Passo 6 - Criar o Arquivo Docker Compose do Koel

Crie e abra o arquivo docker-compose.yml para edição.

$ nano docker-compose.yml

Cole o seguinte código nele.

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

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

O arquivo acima inicia contêineres com base nas imagens do Docker do Koel e MySQL. Ele expõe o Koel na porta 8080 em sua máquina. A música e o arquivo de ambiente são montados nos locais respectivos no contêiner. O diretório para capas de música e o índice de busca, juntamente com os dados do MySQL, são montados como volumes locais. Escolha uma senha forte para as variáveis MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD e combine esses valores com as variáveis para o contêiner Koel no arquivo acima. Para vincular o contêiner Koel ao contêiner do banco de dados, certifique-se de que as variáveis DB_HOST e depends_on tenham o nome do serviço do contêiner do banco de dados.

Passo 7 - Iniciar o Contêiner Koel

Inicie o Contêiner Koel usando o seguinte comando.

$ docker-compose up -d

Inicializar o Koel pela primeira vez

Faça login no shell do Contêiner Koel. koel no comando abaixo refere-se ao nome do contêiner definido pela variável container_name no arquivo Docker compose acima. Se você não tiver um nome de contêiner definido, precisará encontrar o nome do contêiner primeiro e usá-lo no comando a seguir.

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

Execute o seguinte comando para criar uma conta de administrador e inicializar o banco de dados.

$ php artisan koel:init --no-assets

Alterar a Senha do Administrador

O Koel cria uma conta de administrador padrão com as seguintes credenciais.

email: [email protected]
password: KoelIsCool

Você pode alterar a senha da conta de administrador usando o seguinte comando dentro do shell do contêiner.

$ php artisan koel:admin:change-password

Saia do shell do contêiner.

$ exit

Passo 8 - Instalar SSL

Para instalar um certificado SSL usando o Let’s Encrypt, precisamos instalar a ferramenta Certbot.

Primeiro, você precisa baixar e instalar o repositório EPEL.

$ sudo dnf install epel-release

Execute os seguintes comandos para instalar o Certbot.

$ sudo dnf install certbot

Gere o certificado SSL.

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

O comando acima fará o download de um certificado para o diretório /etc/letsencrypt/live/koel.example.com em seu servidor.

Gere um certificado de grupo Diffie-Hellman.

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

Crie um diretório raiz da web para o desafio de auto-renovação do Let’s Encrypt.

$ sudo mkdir -p /var/lib/letsencrypt

Crie um Cron Job para renovar o SSL. Ele será executado todos os dias para verificar o certificado e renová-lo se necessário. Para isso, primeiro crie o arquivo /etc/cron.daily/certbot-renew e abra-o para edição.

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

Cole o seguinte código.

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

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

Altere as permissões do arquivo da tarefa para torná-lo executável.

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

Passo 9 - Instalar o Nginx

Estaremos instalando a versão mais recente do Nginx. Crie e abra o arquivo /etc/yum.repos.d/nginx.repo para edição.

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

Cole as seguintes linhas nele.

[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

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

Instale o Nginx.

$ sudo dnf install nginx

Verifique a instalação.

$ nginx -v
nginx version: nginx/1.20.2

Habilite e inicie o serviço Nginx.

$ sudo systemctl enable nginx --now

Crie e abra o arquivo /etc/nginx/conf.d/koel.conf para edição.

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

Cole o seguinte código nele.

# Redirecionar todo o tráfego não criptografado para criptografado
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;
    }
}

Uma vez terminado, salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado. A configuração acima permite que o Nginx atue como um servidor proxy e se vincule à porta 8080 no localhost.

Abra o arquivo /etc/nginx/nginx.conf para edição.

$ sudo nano /etc/nginx/nginx.conf

Adicione a seguinte linha antes da linha include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Salve o arquivo pressionando Ctrl + X e digitando Y quando solicitado.

Verifique a sintaxe do arquivo de configuração do 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

Reinicie o serviço Nginx para habilitar a nova configuração.

$ sudo systemctl restart nginx

Passo 10 - Acessar o Koel

Você pode acessar o Koel visitando a URL https://koel.example.com em seu navegador. Você será recebido pela seguinte tela de login.

Tela de Login do Koel

Digite [email protected] como seu nome de usuário e a senha que você definiu antes de fazer login. O seguinte painel aparecerá após o login bem-sucedido.

Painel do Koel

Passo 11 - Importar Música

Copie os arquivos de música que você deseja importar para a pasta ~/koel/music do seu sistema. Você pode usar o comando scp para importar os arquivos do seu PC local para o servidor.

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

Uma vez que você tenha copiado os arquivos para a pasta ~/koel/music, execute o seguinte comando para importar a música para o Koel.

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

A música aparecerá na interface web do Koel, e você poderá começar a tocar.

A interface web do Koel também permite que você faça upload de músicas diretamente.

Passo 12 - Atualizar o Koel

Mude para o diretório do Koel.

$ cd ~/koel

Puxe a imagem Docker mais recente do Koel.

$ docker-compose pull

Desligue o contêiner.

$ docker-compose down --remove-orphans

Inicie o contêiner com as imagens atualizadas.

$ docker-compose up -d

Verifique os contêineres Docker.

$ docker ps

Conclusão

Isso conclui o tutorial sobre como instalar o Serviço de Streaming de Música Koel usando Docker em um servidor Rocky Linux. Se você tiver alguma dúvida, poste nos comentários abaixo.

Share: X/Twitter LinkedIn
#Instalação Koel

Receba novas postagens na sua caixa de entrada

Sem spam. Cancele a assinatura a qualquer momento.