서버 설치 · 9 min read · Nov 03, 2025

Rocky Linux 8에서 Docker를 사용하여 Koel 음악 스트리밍 서버 설치하기

Koel은 Laravel PHP 프레임워크로 작성된 웹 기반 오디오 스트리밍 서비스입니다. 개인 음악 컬렉션을 스트리밍하고 전 세계 어디서나 접근할 수 있도록 해줍니다. AAC, OGG, WMA, FLAC 및 APE를 포함한 여러 미디어 형식을 지원합니다.

이 튜토리얼에서는 Rocky Linux 8 머신에서 Docker를 사용하여 Koel 음악 스트리밍 서버를 설치하는 방법을 배웁니다.

필수 조건

  • Rocky Linux 8.5가 실행되는 서버.
  • sudo 권한이 있는 비루트 사용자.
  • 모든 것을 업데이트합니다. $ sudo dnf update
  • 필수 패키지를 설치합니다. $ sudo dnf install yum-utils nano curl
  • 서버를 가리키는 사용자 정의 도메인 이름 koel.example.com.

1단계 - 방화벽 구성

첫 번째 단계는 방화벽을 구성하는 것입니다. Rocky Linux는 Firewalld 방화벽을 사용합니다. 방화벽의 상태를 확인합니다.

$ sudo firewall-cmd --state
running

방화벽은 다양한 영역과 함께 작동하며, 공용 영역이 우리가 사용할 기본 영역입니다. 방화벽에서 활성화된 모든 서비스와 포트를 나열합니다.

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

다음과 같은 출력이 표시되어야 합니다.

cockpit dhcpv6-client ssh

HTTP 및 HTTPS 포트를 허용합니다.

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

방화벽의 상태를 다시 확인합니다.

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

유사한 출력을 볼 수 있어야 합니다.

cockpit dhcpv6-client http https ssh

변경 사항을 적용하기 위해 방화벽을 다시 로드합니다.

$ sudo firewall-cmd --reload

2단계 - Docker 설치

Rocky Linux는 이전 버전의 Docker를 제공합니다. 최신 버전을 설치하려면 먼저 공식 Docker 저장소를 설치합니다.

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

최신 버전의 Docker를 설치합니다.

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

Docker 데몬을 활성화하고 실행합니다.

$ sudo systemctl enable docker --now

실행 중인지 확인합니다.

? 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
...

기본적으로 Docker는 루트 권한을 요구합니다. docker 명령을 실행할 때마다 sudo를 사용하지 않으려면 사용자 이름을 docker 그룹에 추가합니다.

$ sudo usermod -aG docker $(whoami)

이 변경 사항을 활성화하려면 서버에서 로그아웃한 후 동일한 사용자로 다시 로그인해야 합니다.

3단계 - Docker Compose 설치

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

Docker Compose 바이너리 파일에 실행 권한을 적용합니다.

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

설치를 테스트합니다.

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

Docker-compose Bash Completion 스크립트를 설치합니다.

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

bash-completion이 작동하도록 프로필 설정을 다시 로드합니다.

$ source ~/.bashrc

4단계 - Koel 앱 키 생성

컨테이너를 잠시 실행하여 Koel의 앱 키를 생성합니다. 다음 명령을 실행하여 컨테이너를 실행하고 셸에 접근합니다.

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

컨테이너에 들어가면 다음 명령을 실행하여 애플리케이션 키를 생성합니다.

$ php artisan key:generate --force

새로 생성된 앱 키로 수정된 환경 파일을 출력합니다.

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

키 값을 복사하고 컨테이너 셸을 종료합니다.

$ exit

5단계 - Koel 환경 파일 생성

Koel을 위한 디렉토리를 생성합니다.

$ mkdir ~/koel

디렉토리로 이동합니다.

$ cd ~/koel

음악 디렉토리를 생성합니다.

$ mkdir music

.env 파일을 생성하고 엽니다.

$ nano .env

다음 코드를 붙여넣습니다.

APP_NAME=Koel

# A random 32-char string. You can leave this empty if use php artisan koel:init.
APP_KEY=base64:fjtO7aVHHKWfk4DThKqf1nci6o2DuMkNd90TKX6Gj+4=

# The ABSOLUTE path to your media. This value can always be changed later via the web interface.
MEDIA_PATH=/music

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

# The maximum scan time, in seconds. Increase this if you have a huge library.
# Note: This setting doesn't have effect when scanning via koel:sync.
APP_MAX_SCAN_TIME=600

# The memory limit, in MB, used by the scanning process.
# For example, if you want to set a memory limit of 2048MB, enter "2048" (without
# quotes) here.
MEMORY_LIMIT=512

# The streaming method.
# Can be either 'php' (default), 'x-sendfile', or 'x-accel-redirect'
# See https://docs.koel.dev/#streaming-music for more information.
# Note: This setting doesn't have effect if the media needs transcoding (e.g. FLAC).
STREAMING_METHOD=x-sendfile

# If you want Koel to integrate with Last.fm, set the API details here.
# See https://docs.koel.dev/3rd-party.html#last-fm for more information
LASTFM_API_KEY=
LASTFM_API_SECRET=

# If you want to use Amazon S3 with Koel, fill the info here and follow the
# installation guide at https://docs.koel.dev/aws-s3.html
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=

# If you want Koel to integrate with YouTube, set the API key here.
# See https://docs.koel.dev/3rd-party.html#youtube for more information.
YOUTUBE_API_KEY=

# You can also configure Koel to use a CDN to serve the media files.
# This url must be mapped to the home URL of your Koel's installation.
# No trailing slash, please.
CDN_URL=

# The bit rate of the output mp3 stream. Higher value results in better quality,
# but slower streaming and more bandwidth.
OUTPUT_BIT_RATE=128

# Whether to allow song downloading.
# Note that if you're downloading more than one song, Koel will zip them up
# using PHP's ZipArchive. So if the module isn't available in the current
# environment, such a download will (silently) fail.
ALLOW_DOWNLOAD=true

# If this is set to true, the query to get artist, album, and song information will be cached.
# This can give a boost to Koel's boot time, especially if your library is huge.
# However, the cache deserialization process can be memory sensitive, so if you encounter
# errors, try setting this to false.
CACHE_MEDIA=true

# Koel attempts to detect if your website use HTTPS and generates secure URLs accordingly.
# If this attempts for any reason, you can force it by setting this value to true.
FORCE_HTTPS=true

# The variables below are Laravel-specific.
# You can change them if you know what you're doing. Otherwise, just leave them as-is.
APP_LOG_LEVEL=debug
BROADCAST_DRIVER=log
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_DRIVER=sync

파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다.

위의 대부분 설정은 자명합니다. 작동하게 하려면 다음 설정을 구성해야 합니다. 이전 단계에서 생성된 앱 키를 APP_KEY 변수에 붙여넣습니다. APP_URL 아래에 도메인 이름을 입력하고 서버의 리소스에 따라 MB 단위로 메모리 제한을 설정합니다. Koel의 도커 이미지는 Apache를 사용하고 사전 구성되어 있으므로 스트리밍 방법을 x-sendfile로 설정했습니다. FORCE_HTTPS 설정은 true로 설정되어 있습니다. 이는 Nginx를 로드 밸런서로 사용하고 Let’s Encrypt SSL을 통해 Koel을 웹에 제공할 것이기 때문입니다. Koel과 함께 사용하려는 다른 서비스도 구성합니다.

6단계 - Koel Docker Compose 파일 생성

docker-compose.yml 파일을 생성하고 편집을 위해 엽니다.

$ nano docker-compose.yml

다음 코드를 붙여넣습니다.

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

파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다.

위의 파일은 Koel 및 MySQL의 도커 이미지를 기반으로 컨테이너를 시작합니다. Koel을 머신의 포트 8080에 노출합니다. 음악 및 환경 파일은 컨테이너의 해당 위치에 마운트됩니다. 음악 커버 및 검색 인덱스 디렉토리와 MySQL 데이터는 로컬 볼륨으로 마운트됩니다. MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD 변수에 대해 강력한 비밀번호를 선택하고 위의 파일에서 Koel 컨테이너의 변수와 일치시킵니다. Koel 컨테이너를 데이터베이스 컨테이너와 연결하려면 DB_HOSTdepends_on 변수가 데이터베이스 컨테이너의 서비스 이름과 동일해야 합니다.

7단계 - Koel 컨테이너 시작

다음 명령을 사용하여 Koel 컨테이너를 시작합니다.

$ docker-compose up -d

처음으로 Koel 초기화

Koel 컨테이너 셸에 로그인합니다. 아래 명령의 koel은 위의 Docker compose 파일에서 container_name 변수로 설정된 컨테이너의 이름을 나타냅니다. 컨테이너 이름이 설정되어 있지 않으면 먼저 컨테이너 이름을 찾아야 하며, 다음 명령에서 해당 이름을 사용해야 합니다.

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

다음 명령을 실행하여 관리자 계정을 생성하고 데이터베이스를 초기화합니다.

$ php artisan koel:init --no-assets

관리자 비밀번호 변경

Koel은 다음 자격 증명으로 기본 관리자 계정을 생성합니다.

email: [email protected]
password: KoelIsCool

컨테이너 셸 내에서 다음 명령을 사용하여 관리자 계정의 비밀번호를 변경할 수 있습니다.

$ php artisan koel:admin:change-password

컨테이너 셸을 종료합니다.

$ exit

8단계 - SSL 설치

Let’s Encrypt를 사용하여 SSL 인증서를 설치하려면 Certbot 도구를 설치해야 합니다.

먼저 EPEL 저장소를 다운로드하고 설치해야 합니다.

$ sudo dnf install epel-release

다음 명령을 실행하여 Certbot을 설치합니다.

$ sudo dnf install certbot

SSL 인증서를 생성합니다.

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

위 명령은 서버의 /etc/letsencrypt/live/koel.example.com 디렉토리에 인증서를 다운로드합니다.

Diffie-Hellman 그룹 인증서를 생성합니다.

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

Let’s Encrypt 자동 갱신을 위한 챌린지 웹 루트 디렉토리를 생성합니다.

$ sudo mkdir -p /var/lib/letsencrypt

SSL을 갱신하기 위한 Cron 작업을 생성합니다. 매일 실행되어 인증서를 확인하고 필요 시 갱신합니다. 먼저 /etc/cron.daily/certbot-renew 파일을 생성하고 편집을 위해 엽니다.

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

다음 코드를 붙여넣습니다.

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

파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다.

작업 파일의 권한을 변경하여 실행 가능하게 만듭니다.

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

9단계 - Nginx 설치

최신 버전의 Nginx를 설치합니다. /etc/yum.repos.d/nginx.repo 파일을 생성하고 편집을 위해 엽니다.

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

다음 줄을 붙여넣습니다.

[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

파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다.

Nginx를 설치합니다.

$ sudo dnf install nginx

설치를 확인합니다.

$ nginx -v
nginx version: nginx/1.20.2

Nginx 서비스를 활성화하고 시작합니다.

$ sudo systemctl enable nginx --now

/etc/nginx/conf.d/koel.conf 파일을 생성하고 편집을 위해 엽니다.

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

다음 코드를 붙여넣습니다.

# Redirect all non-encrypted to encrypted
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;
    }
}

작업이 끝나면 파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다. 위의 구성은 Nginx가 프록시 서버로 작동하고 localhost의 포트 8080에 바인딩할 수 있도록 합니다.

/etc/nginx/nginx.conf 파일을 편집을 위해 엽니다.

$ sudo nano /etc/nginx/nginx.conf

include /etc/nginx/conf.d/*.conf; 줄 앞에 다음 줄을 추가합니다.

server_names_hash_bucket_size  64;

파일을 저장하려면 Ctrl + X를 누르고 프롬프트가 나타나면 Y를 입력합니다.

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

새 구성을 활성화하기 위해 Nginx 서비스를 재시작합니다.

$ sudo systemctl restart nginx

10단계 - Koel 접근

브라우저에서 https://koel.example.com URL을 방문하여 Koel에 접근할 수 있습니다. 다음 로그인 화면이 표시됩니다.

Koel 로그인 화면

사용자 이름으로 [email protected]를 입력하고 로그인 전에 설정한 비밀번호를 입력합니다. 성공적으로 로그인하면 다음 대시보드가 나타납니다.

Koel 대시보드

11단계 - 음악 가져오기

가져오려는 음악 파일을 시스템의 ~/koel/music 폴더에 복사합니다. scp 명령을 사용하여 로컬 PC에서 서버로 파일을 가져올 수 있습니다.

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

파일을 ~/koel/music 폴더에 복사한 후 다음 명령을 실행하여 Koel에 음악을 가져옵니다.

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

음악은 Koel의 웹 인터페이스에 표시되며 재생을 시작할 수 있습니다.

Koel의 웹 인터페이스는 노래를 직접 업로드할 수도 있습니다.

12단계 - Koel 업데이트

Koel 디렉토리로 전환합니다.

$ cd ~/koel

최신 Koel Docker 이미지를 가져옵니다.

$ docker-compose pull

컨테이너를 종료합니다.

$ docker-compose down --remove-orphans

업데이트된 이미지로 컨테이너를 시작합니다.

$ docker-compose up -d

Docker 컨테이너를 확인합니다.

$ docker ps

결론

이로써 Rocky Linux 서버에서 Docker를 사용하여 Koel 음악 스트리밍 서비스를 설치하는 튜토리얼이 완료되었습니다. 질문이 있으시면 아래 댓글로 남겨주세요.

Share: X/Twitter LinkedIn

새 게시물을 받은 편지함에서 받기

스팸은 없습니다. 언제든지 구독 해지 가능합니다.