From 55e46a55f01f15b9223f219bcfc2d685387cfcac Mon Sep 17 00:00:00 2001 From: AEnterprise Date: Sun, 31 Aug 2025 13:09:44 +0200 Subject: [PATCH 1/4] add koel-init to do init tasks and add the flags to the docs, init is default, optimizing isn't --- .dockerignore | 1 + Dockerfile | 1 + README.md | 4 ++++ koel-entrypoint | 5 ++++- koel-init | 20 ++++++++++++++++++++ 5 files changed, 30 insertions(+), 1 deletion(-) create mode 100755 koel-init diff --git a/.dockerignore b/.dockerignore index 7987a48..21eb8bf 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,3 +5,4 @@ !/apache.conf !/php.ini !/koel-entrypoint +!/koel-init \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 089620a..0e537d8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -124,6 +124,7 @@ ENV FFMPEG_PATH=/usr/bin/ffmpeg \ # Setup bootstrap script. COPY koel-entrypoint /usr/local/bin/ +COPY koel-init /usr/local/bin/ ENTRYPOINT ["koel-entrypoint"] CMD ["apache2-foreground"] diff --git a/README.md b/README.md index 8c5a5a0..d766c80 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,8 @@ docker-compose -f ./docker-compose.postgres.yml up -d ## The `koel:init` command +This command is automatically ran when the container starts, but can be disabled if you want to do some manual adjustments first. As such it is often sufficient to provide the needed env variables to the container to setup koel. + For the first installation and every subsequent upgrade, you will need to run the `koel:init` command, which handles migrations and other setup tasks. For instance, during the first run, this command will generate the `APP_KEY`, create the default admin user, and initialize the database. For subsequent runs, it will apply any new migrations and update the database schema as needed. @@ -189,6 +191,7 @@ For all new songs, the search index will be automatically populated by `php arti > [!IMPORTANT] > This list is not exhaustive and may not be up-to-date. See [`.env.example`][koel-env-example] for a complete reference. +- `SKIP_INIT` : set a value to prevent the container from automatically running the init script on startup - `DB_CONNECTION`: `mysql` OR `pgsql` OR `sqlsrv` OR `sqlite-persistent`. Corresponds to the type of database being used with Koel. - `DB_HOST`: `database`. The name of the Docker container hosting the database. Koel needs to be on the same Docker network to find the database by its name. - `DB_USERNAME`: `koel`. If you change it, also change it in the database container. @@ -199,6 +202,7 @@ For all new songs, the search index will be automatically populated by `php arti - `MEMORY_LIMIT`: The amount of memory in MB for the scanning process. Increase this value if `php artisan koel:scan` runs out of memory. - `LASTFM_API_KEY` and `LASTFM_API_SECRET`: Enables Last.fm integration. See https://docs.koel.dev/3rd-party.html#last-fm - `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`: Enables Spotify integration. See https://docs.koel.dev/3rd-party.html#spotify +- `OPTIMIZE_CONFIG` Preload and optimize the config. This disables your ability to do config edits while the container is running. If you enable this every config change will require a container restart to apply. ## Volumes diff --git a/koel-entrypoint b/koel-entrypoint index cf21cd4..de2e25f 100755 --- a/koel-entrypoint +++ b/koel-entrypoint @@ -1,10 +1,13 @@ -#!/bin/bash +#!/bin/sh set -e # Change to program root directory. cd /var/www/html +# Run the koel-init script to (optionally) optimize configs and (optionally) run initialize/update koel +su -s '/bin/sh' -c "/usr/local/bin/koel-init" www-data + # Run the next entrypoint in the chain. echo "running docker-php-entrypoint with arguments $@" docker-php-entrypoint $@ diff --git a/koel-init b/koel-init new file mode 100755 index 0000000..1821fbd --- /dev/null +++ b/koel-init @@ -0,0 +1,20 @@ +#!/bin/bash + +if [[ -z "${SKIP_INIT}" ]]; then + + if [[ -z "${OPTIMIZE_CONFIG}" ]]; then + echo "Config not optimized, if your config is locked in you can enable the OPTIMIZE_CONFIG option. Enabling this will optimize your config, but YOU WILL NOT BE ABLE TO MAKE CONFIG EDITS WITHOUT RESTARING THE CONTAINER" + else + echo "Optimizing config..." + # clear before caching, in case this is a container reboot and it was already cached from before + php artisan config:clear + php artisan config:cache + fi + + # Invoke the init script so database migrations run and the config is at least partially validated + echo "Running installer..." + php artisan koel:init --no-assets --no-interaction + php artisan koel:doctor +else + echo "Skipped init, koel might not be able to run if it is misconfigured or your database is out of date. This should not be used outside of debugging or manual initial setups!" +fi \ No newline at end of file From 29b22f3c522905b99a12f83b39de114c75978d34 Mon Sep 17 00:00:00 2001 From: AEnterprise Date: Sun, 31 Aug 2025 16:41:19 +0200 Subject: [PATCH 2/4] warn about missing .env file instead of running the init without it --- koel-init | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/koel-init b/koel-init index 1821fbd..281bc01 100755 --- a/koel-init +++ b/koel-init @@ -1,5 +1,13 @@ #!/bin/bash +if [[ ! -f /var/www/html/.env ]]; then + echo "No .env file found in /var/www/html, please make sure to mount an .env config file to store the configuration, you can use the koel:init command for a guided setup" + echo "" + echo "See https://github.com/koel/docker?tab=readme-ov-file#the-koelinit-command for more information about the init command" + echo "See https://github.com/koel/koel/blob/master/.env.example for an example env file if you want to change other configuration options as well or do a manual setup" + exit 0 +fi + if [[ -z "${SKIP_INIT}" ]]; then if [[ -z "${OPTIMIZE_CONFIG}" ]]; then From e7866fce8ded0135e97d57484927b8c9495325a7 Mon Sep 17 00:00:00 2001 From: AEnterprise Date: Sat, 3 Jan 2026 11:16:28 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Phan An --- .dockerignore | 2 +- README.md | 4 ++-- koel-init | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.dockerignore b/.dockerignore index 21eb8bf..b3c3f71 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,4 +5,4 @@ !/apache.conf !/php.ini !/koel-entrypoint -!/koel-init \ No newline at end of file +!/koel-init diff --git a/README.md b/README.md index d766c80..fb03194 100644 --- a/README.md +++ b/README.md @@ -191,7 +191,7 @@ For all new songs, the search index will be automatically populated by `php arti > [!IMPORTANT] > This list is not exhaustive and may not be up-to-date. See [`.env.example`][koel-env-example] for a complete reference. -- `SKIP_INIT` : set a value to prevent the container from automatically running the init script on startup +- `SKIP_INIT`: Prevents the container from automatically running the init script on startup. - `DB_CONNECTION`: `mysql` OR `pgsql` OR `sqlsrv` OR `sqlite-persistent`. Corresponds to the type of database being used with Koel. - `DB_HOST`: `database`. The name of the Docker container hosting the database. Koel needs to be on the same Docker network to find the database by its name. - `DB_USERNAME`: `koel`. If you change it, also change it in the database container. @@ -202,7 +202,7 @@ For all new songs, the search index will be automatically populated by `php arti - `MEMORY_LIMIT`: The amount of memory in MB for the scanning process. Increase this value if `php artisan koel:scan` runs out of memory. - `LASTFM_API_KEY` and `LASTFM_API_SECRET`: Enables Last.fm integration. See https://docs.koel.dev/3rd-party.html#last-fm - `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`: Enables Spotify integration. See https://docs.koel.dev/3rd-party.html#spotify -- `OPTIMIZE_CONFIG` Preload and optimize the config. This disables your ability to do config edits while the container is running. If you enable this every config change will require a container restart to apply. +- `OPTIMIZE_CONFIG` Preloads and optimizes koel's configuration. This disables config modifications while the container is running. If you enable this, every change to the configuration will require a container restart to be applied. ## Volumes diff --git a/koel-init b/koel-init index 281bc01..caad3ec 100755 --- a/koel-init +++ b/koel-init @@ -1,17 +1,17 @@ #!/bin/bash if [[ ! -f /var/www/html/.env ]]; then - echo "No .env file found in /var/www/html, please make sure to mount an .env config file to store the configuration, you can use the koel:init command for a guided setup" + echo "No .env file found in /var/www/html. Make sure to mount a .env file to store the configuration. You can use the koel:init command (see https://github.com/koel/docker#the-koelinit-command) for a guided setup." echo "" echo "See https://github.com/koel/docker?tab=readme-ov-file#the-koelinit-command for more information about the init command" - echo "See https://github.com/koel/koel/blob/master/.env.example for an example env file if you want to change other configuration options as well or do a manual setup" + echo "See https://github.com/koel/koel/blob/master/.env.example for an example .env file." exit 0 fi if [[ -z "${SKIP_INIT}" ]]; then if [[ -z "${OPTIMIZE_CONFIG}" ]]; then - echo "Config not optimized, if your config is locked in you can enable the OPTIMIZE_CONFIG option. Enabling this will optimize your config, but YOU WILL NOT BE ABLE TO MAKE CONFIG EDITS WITHOUT RESTARING THE CONTAINER" + echo "Config not optimized. You can optimize the config with `OPTIMIZE_CONFIG`. Note that this will prevent config modifications from being applied until the container is restarted." else echo "Optimizing config..." # clear before caching, in case this is a container reboot and it was already cached from before @@ -24,5 +24,5 @@ if [[ -z "${SKIP_INIT}" ]]; then php artisan koel:init --no-assets --no-interaction php artisan koel:doctor else - echo "Skipped init, koel might not be able to run if it is misconfigured or your database is out of date. This should not be used outside of debugging or manual initial setups!" -fi \ No newline at end of file + echo "Initialization skipped. koel might not work properly if it is misconfigured or if the database is out of date. This should not be used outside of debugging or manual initial setups!" +fi From 48dd07f1f59eb8ea82298327e2244de49e193e9d Mon Sep 17 00:00:00 2001 From: AEnterprise Date: Sat, 3 Jan 2026 11:16:45 +0100 Subject: [PATCH 4/4] Update koel-init Co-authored-by: Phan An --- koel-init | 1 - 1 file changed, 1 deletion(-) diff --git a/koel-init b/koel-init index caad3ec..27aa1f6 100755 --- a/koel-init +++ b/koel-init @@ -3,7 +3,6 @@ if [[ ! -f /var/www/html/.env ]]; then echo "No .env file found in /var/www/html. Make sure to mount a .env file to store the configuration. You can use the koel:init command (see https://github.com/koel/docker#the-koelinit-command) for a guided setup." echo "" - echo "See https://github.com/koel/docker?tab=readme-ov-file#the-koelinit-command for more information about the init command" echo "See https://github.com/koel/koel/blob/master/.env.example for an example .env file." exit 0 fi