Skip to content
BranchesTags

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
scripts
scripts
 
 
.dockerignore
.dockerignore
 
 
.env.example
.env.example
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
Dockerfile
Dockerfile
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 

Repository files navigation

PSP Palworld Server Docker

A Docker container for running a Windows Palworld Dedicated Server on Linux via GE-Proton, with built-in UE4SS mod framework support and native DLL mod loading.

Why This Project?

Most Palworld Docker servers run the Linux server binary. This project runs the Windows server binary through GE-Proton, which unlocks:

  • UE4SS mod support -- Lua and C++ script mods via the UE4SS framework
  • Native DLL mods -- Proxy DLL mods like PalDefender that require Windows binaries
  • Full mod ecosystem -- Access to the complete Windows modding toolchain

Server Requirements

Resource Minimum Recommended
CPU 4 cores 4+ cores
RAM 16 GB 32 GB
Storage 12 GB 30 GB

The Windows binary running under Proton uses slightly more resources than the native Linux server.

Quick Start

1. Clone the repository

git clone https://github.com/psp/psp-palworld-docker.git
cd psp-palworld-docker

2. Configure environment

cp .env.example .env

Edit .env and set at minimum:

SERVER_NAME=My Palworld Server
SERVER_PASSWORD=changeme
ADMIN_PASSWORD=changemeAdmin

3. Start the server

docker compose up -d

4. View logs

docker compose logs -f

5. Stop the server

docker compose down

Docker Compose

services:
  palworld:
    build: .
    restart: unless-stopped
    container_name: psp-palworld-server
    stop_grace_period: 30s
    ports:
      - 8211:8211/udp      # Game port
      - 27015:27015/udp    # Query port
      - 8212:8212/tcp      # REST API (DO NOT port forward this)
    environment:
      PUID: 1000
      PGID: 1000
      PORT: 8211
      PLAYERS: 16
      SERVER_PASSWORD: "changeme"
      ADMIN_PASSWORD: "changemeAdmin"
      SERVER_NAME: "PSP Palworld Server"
      MULTITHREADING: true
      REST_API_ENABLED: true
      ENABLE_UE4SS: true
    volumes:
      - palworld-data:/palworld/
      - ./mods:/palworld/Pal/Binaries/Win64/Mods/
      - ./logicmods:/palworld/Pal/Content/Paks/LogicMods/
      - ./nativemods:/palworld/nativemods/
      - ./saves:/palworld/Pal/Saved/

volumes:
  palworld-data:

Game Ports

Port Protocol Description
8211 UDP Game port
27015 UDP Query port
8212 TCP REST API (internal only -- do not port forward)

Mod Support

This is the primary reason this project exists. Running the Windows binary via Proton enables the full Palworld modding ecosystem.

UE4SS Mods (Lua / C++ Scripts)

UE4SS is automatically installed when ENABLE_UE4SS=true (default).

Variable Default Description
ENABLE_UE4SS true Enable UE4SS mod framework
UE4SS_VERSION 3.0.1 UE4SS release version to install
UE4SS_FORCE_UPDATE false Force re-download even if already installed

Installing mods:

  1. Place UE4SS script mods in ./mods/ (maps to Win64/Mods/)
  2. Place UE4SS logic mods (.pak files) in ./logicmods/ (maps to Content/Paks/LogicMods/)
  3. Restart the server

UE4SS is automatically configured for headless Docker operation (GUI console disabled, UObject array cache disabled for Proton stability).

Native / Proxy DLL Mods

For mods that use DLL injection (e.g., PalDefender):

  1. Place .dll files and any config folders in ./nativemods/
  2. Restart the server

Files are synced to Win64/ on every boot. Proxy DLLs (d3d9, d3d11, dinput8, dxgi, winhttp, version, winmm, xinput1_3) are automatically added to WINEDLLOVERRIDES.

Environment Variables

Server Configuration

Variable Default Description
TZ UTC Timezone (e.g., America/New_York)
PUID 1000 User ID for file permissions
PGID 1000 Group ID for file permissions
PORT 8211 Game server port (UDP)
QUERY_PORT 27015 Steam query port (UDP)
PLAYERS 16 Maximum player count
SERVER_NAME PSP Palworld Server Server display name
SERVER_DESCRIPTION Modded Palworld Server with UE4SS Server description
SERVER_PASSWORD changeme Server join password (empty = public)
ADMIN_PASSWORD changemeAdmin Admin and REST API password
PUBLIC_IP (empty) Public IP (auto-detected if empty)
PUBLIC_PORT (empty) Public game port
MULTITHREADING true Enable multi-threaded server
COMMUNITY false Show in community server browser
CROSSPLAY_PLATFORMS (Steam,Xbox,PS5,Mac) Allowed platforms

Update Management

Variable Default Description
UPDATE_ON_BOOT true Check for updates on container start
AUTO_UPDATE_ENABLED false Enable automatic update checking
AUTO_UPDATE_CRON_EXPRESSION 0 * * * * Cron schedule for update checks
AUTO_UPDATE_WARN_MINUTES 30 Warning time before auto-update
USE_DEPOT_DOWNLOADER false Use DepotDownloader instead of SteamCMD
INSTALL_BETA_INSIDER false Install beta/insider builds
TARGET_MANIFEST_ID (empty) Lock to a specific game version
STEAM_USERNAME (empty) Steam credentials (for version locking)
STEAM_PASSWORD (empty) Steam credentials (for version locking)

Backups

Variable Default Description
BACKUP_ENABLED true Enable automated backups
BACKUP_CRON_EXPRESSION 0 0 * * * Cron schedule (default: daily at midnight)
DELETE_OLD_BACKUPS false Auto-delete old backups
OLD_BACKUP_DAYS 30 Delete backups older than N days

Backups are stored as palworld-save-YYYY-MM-DD_HH-MM-SS.tar.gz in /palworld/backups/.

Auto Reboot

Variable Default Description
AUTO_REBOOT_ENABLED false Enable scheduled restarts
AUTO_REBOOT_CRON_EXPRESSION 0 0 * * * Cron schedule for restarts
AUTO_REBOOT_WARN_MINUTES 5 Warning time before reboot
AUTO_REBOOT_EVEN_IF_PLAYERS_ONLINE false Reboot even with active players

Requires REST_API_ENABLED=true.

REST API

Variable Default Description
REST_API_ENABLED true Enable the game REST API
REST_API_PORT 8212 REST API port (TCP)

The REST API is required for player logging, auto-update, auto-reboot, and the rest-cli command. Do not port forward this -- it contains your admin password.

Player Logging

Variable Default Description
ENABLE_PLAYER_LOGGING true Track player join/leave events
PLAYER_LOGGING_POLL_PERIOD 5 Polling interval in seconds

Requires REST_API_ENABLED=true.

Logging

Variable Default Description
LOG_FILTER_ENABLED true Enable advanced log filtering
LOG_FORMAT_TYPE default Log format: default, json, logfmt, colored, plain

Discord Webhooks

Variable Default Description
DISCORD_WEBHOOK_URL (empty) Discord webhook URL
DISCORD_SUPPRESS_NOTIFICATIONS false Suppress @ mentions
DISCORD_CONNECT_TIMEOUT 30 Connection timeout (seconds)
DISCORD_MAX_TIMEOUT 30 Total request timeout (seconds)

Each event has three variables for customization:

Pattern Example Description
DISCORD_<EVENT>_MESSAGE DISCORD_PRE_START_MESSAGE Message template
DISCORD_<EVENT>_MESSAGE_ENABLED DISCORD_PRE_START_MESSAGE_ENABLED Enable/disable (true/false)
DISCORD_<EVENT>_MESSAGE_URL DISCORD_PRE_START_MESSAGE_URL Override webhook URL for this event

Available events:

Event Default Message
PRE_UPDATE_BOOT Server is updating...
POST_UPDATE_BOOT Server update complete!
PRE_START Server has been started!
PRE_SHUTDOWN Server is shutting down...
POST_SHUTDOWN Server has been stopped!
PLAYER_JOIN player_name has joined Palworld!
PLAYER_LEAVE player_name has left Palworld.
PRE_BACKUP Creating backup...
POST_BACKUP Backup created at file_path
PRE_BACKUP_DELETE Removing backups older than old_backup_days days
POST_BACKUP_DELETE Removed backups older than old_backup_days days
ERR_BACKUP_DELETE Error message when backup deletion fails

Message templates support variable substitution: player_name, file_path, old_backup_days.

Engine Performance

Variable Default Description
LAN_SERVER_MAX_TICK_RATE 120 LAN server tick rate
NET_SERVER_MAX_TICK_RATE 120 Network server tick rate
CONFIGURED_INTERNET_SPEED 104857600 Internet speed (bytes/sec)
CONFIGURED_LAN_SPEED 104857600 LAN speed (bytes/sec)
MAX_CLIENT_RATE 104857600 Max client rate
MAX_INTERNET_CLIENT_RATE 104857600 Max internet client rate
SMOOTH_FRAME_RATE true Enable frame rate smoothing
SMOOTH_FRAME_RATE_UPPER_LIMIT 120.0 Upper frame rate limit
SMOOTH_FRAME_RATE_LOWER_LIMIT 30.0 Lower frame rate limit
USE_FIXED_FRAME_RATE false Use fixed frame rate
FIXED_FRAME_RATE 120 Fixed frame rate value
MIN_DESIRED_FRAME_RATE 60 Minimum desired frame rate
NET_CLIENT_TICKS_PER_SECOND 120 Client network ticks per second

Game Settings

All standard Palworld game settings are supported as environment variables. These map directly to PalWorldSettings.ini. See .env.example for the full list with defaults.

Click to expand full game settings list
Variable Default
DIFFICULTY None
DAYTIME_SPEEDRATE 1.000000
NIGHTTIME_SPEEDRATE 1.000000
EXP_RATE 1.000000
PAL_CAPTURE_RATE 1.000000
PAL_SPAWN_NUM_RATE 1.000000
PAL_DAMAGE_RATE_ATTACK 1.000000
PAL_DAMAGE_RATE_DEFENSE 1.000000
PLAYER_DAMAGE_RATE_ATTACK 1.000000
PLAYER_DAMAGE_RATE_DEFENSE 1.000000
PLAYER_STOMACH_DECREASE_RATE 1.000000
PLAYER_STAMINA_DECREASE_RATE 1.000000
PLAYER_AUTO_HP_REGEN_RATE 1.000000
PLAYER_AUTO_HP_REGEN_RATE_IN_SLEEP 1.000000
PAL_STOMACH_DECREASE_RATE 1.000000
PAL_STAMINA_DECREASE_RATE 1.000000
PAL_AUTO_HP_REGEN_RATE 1.000000
PAL_AUTO_HP_REGEN_RATE_IN_SLEEP 1.000000
BUILD_OBJECT_HP_RATE 1.000000
BUILD_OBJECT_DAMAGE_RATE 1.000000
BUILD_OBJECT_DETERIORATION_DAMAGE_RATE 1.000000
COLLECTION_DROP_RATE 1.000000
COLLECTION_OBJECT_HP_RATE 1.000000
COLLECTION_OBJECT_RESPAWN_SPEED_RATE 1.000000
ENEMY_DROP_ITEM_RATE 1.000000
DEATH_PENALTY All
ENABLE_PLAYER_TO_PLAYER_DAMAGE False
ENABLE_FRIENDLY_FIRE False
ENABLE_INVADER_ENEMY True
ACTIVE_UNKO False
ENABLE_AIM_ASSIST_PAD True
ENABLE_AIM_ASSIST_KEYBOARD False
DROP_ITEM_MAX_NUM 3000
DROP_ITEM_MAX_NUM_UNKO 100
BASE_CAMP_MAX_NUM 128
BASE_CAMP_WORKER_MAX_NUM 15
DROP_ITEM_ALIVE_MAX_HOURS 1.000000
AUTO_RESET_GUILD_NO_ONLINE_PLAYERS False
AUTO_RESET_GUILD_TIME_NO_ONLINE_PLAYERS 72.000000
GUILD_PLAYER_MAX_NUM 20
BASE_CAMP_MAX_NUM_IN_GUILD 4
PAL_EGG_DEFAULT_HATCHING_TIME 72.000000
WORK_SPEED_RATE 1.000000
AUTO_SAVE_SPAN 30.000000
IS_MULTIPLAY False
IS_PVP False
HARDCORE False
PAL_LOST False
CAN_PICKUP_OTHER_GUILD_DEATH_PENALTY_DROP False
ENABLE_NON_LOGIN_PENALTY True
ENABLE_FAST_TRAVEL True
IS_START_LOCATION_SELECT_BY_MAP True
EXIST_PLAYER_AFTER_LOGOUT False
ENABLE_DEFENSE_OTHER_GUILD_PLAYER False
INVISIBLE_OTHER_GUILD_BASE_CAMP_AREA_FX False
BUILD_AREA_LIMIT False
ITEM_WEIGHT_RATE 1.000000
COOP_PLAYER_MAX_NUM 4
SHOW_PLAYER_LIST True
ENABLE_PREDATOR_BOSS_PAL True
MAX_BUILDING_LIMIT_NUM 0
CROSSPLAY_PLATFORMS (Steam,Xbox,PS5,Mac)
ALLOW_GLOBAL_PALBOX_EXPORT True
ALLOW_GLOBAL_PALBOX_IMPORT False
EQUIPMENT_DURABILITY_DAMAGE_RATE 1.000000
SUPPLY_DROP_SPAN 180
CHAT_POST_LIMIT_PER_MINUTE 10
RCON_ENABLED False
RCON_PORT 25575
ALLOW_CLIENT_MOD False

Container Commands

Run commands inside the container with docker exec:

# Create a backup
docker exec psp-palworld-server backup

# Check for updates
docker exec psp-palworld-server update

# Restore from a backup (interactive)
docker exec -it psp-palworld-server restore

REST API CLI

# Server info
docker exec psp-palworld-server rest-cli info

# List online players
docker exec psp-palworld-server rest-cli players

# Broadcast a message
docker exec psp-palworld-server rest-cli announce "Server restarting in 10 minutes"

# Save the world
docker exec psp-palworld-server rest-cli save

# Graceful shutdown (60 second countdown)
docker exec psp-palworld-server rest-cli shutdown 60 "Server shutting down"

# Kick a player
docker exec psp-palworld-server rest-cli kick steam_00000000000000000 "Reason"

# Ban a player
docker exec psp-palworld-server rest-cli ban steam_00000000000000000 "Reason"

# Unban a player
docker exec psp-palworld-server rest-cli unban steam_00000000000000000

Volume Mounts

Host Path Container Path Description
palworld-data (named volume) /palworld/ Game server files
./mods/ /palworld/Pal/Binaries/Win64/Mods/ UE4SS script mods
./logicmods/ /palworld/Pal/Content/Paks/LogicMods/ UE4SS logic mods (.pak)
./nativemods/ /palworld/nativemods/ Native DLL mods
./saves/ /palworld/Pal/Saved/ Save data and configs

Game files use a named volume (palworld-data) for performance. Bind mounts for game files can crash on Docker Desktop / WSL2.

How It Works

  1. SteamCMD downloads the Windows server files (+@sSteamCmdForcePlatformType windows)
  2. GE-Proton (GE-Proton10-34) runs PalServer-Win64-Shipping-Cmd.exe via its Wine/Proton compatibility layer
  3. UE4SS loads as a proxy DLL (dwmapi.dll) and enables Lua/C++ script mods
  4. Native mods are synced from ./nativemods/ to Win64/ with automatic WINEDLLOVERRIDES configuration
  5. Game settings are generated from environment variables into PalWorldSettings.ini and Engine.ini

Editing Server Settings Manually

If you prefer to edit configuration files directly instead of using environment variables, set DISABLE_GENERATE_SETTINGS=true and edit:

  • Game settings: ./saves/Config/WindowsServer/PalWorldSettings.ini
  • Engine settings: ./saves/Config/WindowsServer/Engine.ini

Acknowledgments

Inspired by the work of the Palworld Docker community:

License

MIT

About

Palworld Dedicated Server Docker with Windows mod support (UE4SS + native DLLs) via GE-Proton

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages