solves #273

Author: jammsen

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Updated docker-image pinning and github-actions versions by @jammsen (#312)
 - Refactored from docker-compose.yml to new standard compose.yml including gitignore by @jammsen (#312)
 - Implemented finally a version of auto-updating the compose.yml @jahusa02 (#188)
+- Added the function to run a custom script, that the user can place at /palworld/custom-script - Off by default, completely opt-in and added a very explicit PSA in the README.md for it by @jammsen for @Jadiction (#273)
 
 ## 2025-09-06
 

Dockerfile

@@ -77,6 +77,9 @@ ENV DEBIAN_FRONTEND=noninteractive \
     RCON_PLAYER_DEBUG=false \
     RCON_PLAYER_DETECTION_STARTUP_DELAY=60 \
     RCON_PLAYER_DETECTION_CHECK_INTERVAL=15 \
+    # Custom-script-settings
+    CUSTOM_SCRIPT_ENABLED=false \
+    CUSTOM_SCRIPT_PATH="/palworld/custom-script.sh" \
     # Webhook-settings
     WEBHOOK_ENABLED=false \
     WEBHOOK_DEBUG_ENABLED=false \

README.md

@@ -16,6 +16,18 @@ This Docker image includes a Palworld Dedicated Server based on Linux and Docker
 
 ___
 
+> [!CAUTION]
+> **Public Service Announcement — Custom Script Feature**
+>
+> After many community requests, this image now supports running a custom script before the server starts.
+> This feature is entirely **opt-in** and is controlled by the `CUSTOM_SCRIPT_ENABLED` environment variable, which defaults to `false`.
+>
+> **This image will never ship with a custom script of any kind.**
+>
+> If you come across a Docker image that appears to be this one but includes a bundled custom script, please be careful — it is not this image and I have no affiliation with it.
+>
+> This feature was added at the request of the community. While I am glad to offer the option, I will not be providing support for it, and I refuse to accept **any liability** for any harm, data loss, corruption, or security issues that may result from its use. Please use it at your own discretion. — Public Service Announcement.
+
 ## Table of Contents
 
 - [Docker - Palworld Dedicated Server](#docker---palworld-dedicated-server)

default.env

@@ -20,6 +20,9 @@ RCON_PLAYER_DETECTION=true
 RCON_PLAYER_DEBUG=false
 RCON_PLAYER_DETECTION_STARTUP_DELAY=60
 RCON_PLAYER_DETECTION_CHECK_INTERVAL=15
+# Custom-script-settings
+CUSTOM_SCRIPT_ENABLED=false
+CUSTOM_SCRIPT_PATH=/palworld/custom-script.sh
 # Webhook-settings
 WEBHOOK_ENABLED=false
 WEBHOOK_DEBUG_ENABLED=false

docs/ENV_VARS.md

@@ -29,6 +29,8 @@ These settings control the behavior of the Docker container:
 | RCON_PLAYER_DEBUG                    | Set to enabled will post debug messages to the console output                                                                                       | false                          | Boolean                               |
 | RCON_PLAYER_DETECTION_STARTUP_DELAY  | Initial delay for start checking for players, consider steam-updates and server start up in seconds                                                 | 60                             | Integer                               |
 | RCON_PLAYER_DETECTION_CHECK_INTERVAL | Interval in seconds to wait for next check in the infinite loop                                                                                     | 15                             | Integer                               |
+| CUSTOM_SCRIPT_ENABLED                | Set to enabled will execute a custom script before the gameserver starts, see `CUSTOM_SCRIPT_PATH`                                                  | false                          | Boolean                               |
+| CUSTOM_SCRIPT_PATH                   | Absolute path to the custom script to execute; the file must exist at container runtime (e.g. mounted via a volume)                                 | /palworld/custom-script.sh     | String (absolute path)                |
 | WEBHOOK_ENABLED                      | Set to enabled will send webhook notifications, NEEDS `WEBHOOK_URL`                                                                                 | false                          | Boolean                               |
 | WEBHOOK_DEBUG_ENABLED                | Set to enabled will enable feedback of curl and not use --silent                                                                                    | false                          | Boolean                               |
 | WEBHOOK_URL                          | Defines the url the webhook to send data to                                                                                                         |                                | Url                                   |

includes/server.sh

@@ -4,6 +4,52 @@ source /includes/colors.sh
 source /includes/rcon.sh
 source /includes/webhook.sh
 
+function check_and_run_custom_script() {
+    if [[ -z $CUSTOM_SCRIPT_ENABLED ]] || [[ "${CUSTOM_SCRIPT_ENABLED,,}" != "true" ]]; then
+        return 0
+    fi
+
+    ei ">>> Custom script is enabled"
+
+    # Validate CUSTOM_SCRIPT_PATH is set
+    if [[ -z $CUSTOM_SCRIPT_PATH ]]; then
+        ee ">>> CUSTOM_SCRIPT_PATH is not set, skipping custom script execution"
+        return 0
+    fi
+
+    # Security: require an absolute path to prevent relative-path or injection tricks
+    if [[ "$CUSTOM_SCRIPT_PATH" != /* ]]; then
+        ee ">>> CUSTOM_SCRIPT_PATH must be an absolute path (got: '$CUSTOM_SCRIPT_PATH'), skipping"
+        return 0
+    fi
+
+    # Security: reject any path containing '..' to prevent traversal
+    if [[ "$CUSTOM_SCRIPT_PATH" == *".."* ]]; then
+        ee ">>> CUSTOM_SCRIPT_PATH must not contain '..', skipping"
+        return 0
+    fi
+
+    # Check that the target is a regular file
+    if [[ ! -f "$CUSTOM_SCRIPT_PATH" ]]; then
+        ew "> Custom script not found at '$CUSTOM_SCRIPT_PATH', skipping"
+        return 0
+    fi
+
+    ei "> Found custom script at '$CUSTOM_SCRIPT_PATH', preparing to execute"
+    chmod u+x "$CUSTOM_SCRIPT_PATH"
+
+    ei "> Executing custom script..."
+    local custom_script_exit_code=0
+    # The '||' prevents set -e from aborting on a non-zero exit so we can log it
+    "$CUSTOM_SCRIPT_PATH" || custom_script_exit_code=$?
+
+    if [[ $custom_script_exit_code -ne 0 ]]; then
+        ee ">>> Custom script exited with error code $custom_script_exit_code, continuing server startup"
+    else
+        es ">>> Custom script completed successfully"
+    fi
+}
+
 function start_server() {
     cd "$GAME_ROOT" || exit
     setup_configs
@@ -20,6 +66,8 @@ function start_server() {
     if [[ -n $WEBHOOK_ENABLED ]] && [[ "${WEBHOOK_ENABLED,,}" == "true" ]]; then
         send_start_notification
     fi
+    check_and_run_custom_script
+
     es ">>> Starting the gameserver"
     ./PalServer.sh "${START_OPTIONS[@]}"
 }