서버 설치 · 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_HOST 및 depends_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에 접근할 수 있습니다. 다음 로그인 화면이 표시됩니다.

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

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 음악 스트리밍 서비스를 설치하는 튜토리얼이 완료되었습니다. 질문이 있으시면 아래 댓글로 남겨주세요.
새 게시물을 받은 편지함에서 받기
스팸은 없습니다. 언제든지 구독 해지 가능합니다.