Skip to content

TheSudoYT/terraform-aws-palworld

Repository files navigation

Palworld Dedicated Server Terraform Module

Palworld Server Infrastructure Terraform module.

Donate

I do this in my free time. Consider donating to keep the project going and motivate me to maintain the repo, add new features, etc :)

Support on Patreon

Support on Patreon

Support on By Me A Coffee

Support on BuyMeACoffee

Subscribe

Subscribe on YouTube

About

This module allows you to quickly deploy an Palworld server on AWS.

Key Features

  • Palworldrunning on Ubuntu
  • The ability to use an existing PalWorldSettings.ini
  • PalWorldSettings.ini settings are configurable inputs for creating a brand new configuration
  • Ability to store backups in S3 at a defined interval
  • Ability to start from existing save data
  • AWS SSM or SSH connectivity

How to Use

Prerequisites

You must have the following to use this Terraform module:

Usage

  1. Create a file named main.tf
  2. Add the following as a minimum. See all available inputs in the "Inputs" section of this README. Inputs not defined will use their default values.
module "palworld" {
  source  = "TheSudoYT/palworld/aws"

  instance_type                 = "t3.xlarge"
  create_ssh_key                = true
  ssh_public_key                = "../../palworld_public_key.pub"
  server_name                   = "palworld-on-aws"
  server_player_max_num         = 32
}
  1. Choose your inputs - PalWorldSettings.ini inputs use default values unless you provide a value OTHER than the default value. Palworld will use the settings from a custom PalWorldSettings.ini file if you choose to use one. Modifying an input that is a PalWorldSettings.ini setting while also using a custom PalWorldSettings.ini file will result ONLY the values in your custom .ini file being used.

Warning

Any of the inputs that are also settings in the PalWorldSettings.ini file will be ignored if use_custom_palworldsettings = true. For example, if you say exp_rate = 3.0 and also say use_custom_palworldsettings = true then the value in your custom PalWorldSettings.ini will be used and the value of exp_rate will be ignored.

  1. Initialize Terraform - Run terraform init to download the module and providers.
  2. Create the Palworld server and Infrastructure - Run terraform apply to start deploying the infrastructure.

Accessing the Server

Warning

As of Jan 23, 2024 users are reporting a bug preventing servers from appearing in the community servers list or search filter. If this happens you can still connect to the server using the EC2 instance IP address and the public_port you have set (default 8211)

Note

In testing it takes approximately 10 minutes on a t3.xlarge for steam to download and configure Palworld.

The terraform apply will complete, but the server will not appear in the server list until this completes. You can SSH into your server ssh -i my_palworld_key.pem ubuntu@1.2.3.4 and use journalctl -xu cloud-final to monitor the install. See the troubleshooting section of the README if you continue to have problems.

Note

In testing it takes approximately 3 to 5 minutes for your server to appear on the community server list after installation is complete.

Backups

This module offers an optional backup feature, designed to safeguard your Pal/Saved/SaveGame directory by periodically copying it to an Amazon S3 bucket. When enabled, the backup feature automatically archives the specified directory to a designated S3 bucket at intervals defined by a cron expression. The retention period of these backups in S3 is controlled by the s3_bucket_backup_retention parameter, allowing for cost-effective storage management.

Note

Enabling this creates an additional S3 bucket. In testing, this adds an additional 0.10 USD ( 10 cents ) a month on average depending on the duration of backup retention, how often you backup, and how often you restore from backup. https://calculator.aws/#/addService

2 Files will be created on the Palworld server; palworld_backup_script.sh on install and palworld_backup_log.log AFTER the first backup job runs.

The backup should be visible in the AWS S3 bucket after the first specified backup interval time frame passes.

Using an Existing PalWorldSettings.ini

You can use an existing PalWorldSettings.ini so that the server starts with your custom settings. The following inputs are required to do this:

Warning

Any of the inputs that are also settings in the PalWorldSettings.ini file will be ignored if use_custom_palworldsettings = true. For example, if you say exp_rate = 3.0 and also say use_custom_palworldsettings = true then the value in your custom PalWorldSettings.ini will be used and the value of exp_rate will be ignored.

Input Description
use_custom_palworldsettings = true Must be set to pass a custom PalWorldSettings.ini to the server on startup
custom_palworldsettings_s3 = true Cannot be set when custom_palworldsettings_github = true. Set to true if you would like to upload an existing PalWorldSettings.ini to an S3 bucket during terraform apply. Setting this to true will create an S3 bucket and upload the file from your PC to the S3 bucket. It will then download the file from the S3 bucket on server startup. You MUST also set palworldsettings_ini_path as a path on your local system relative to the terraform working directory. It is easiest to just place PalWorldSettings.ini in the root of your terraform working directory and just provide palworldsettings_ini_path = PalWorldSettings.ini.
palworldsettings_ini_path = "path/on/my/pc" A path on your local system relative to the terraform working directory. It is easiest to just place PalWorldSettings.ini in the root of your terraform working directory and just provide game_user_settings_ini_path = PalWorldSettings.ini. Only used when custom_palworldsettings_s3 = true.
custom_palworldsettings_github = true Cannot be set when custom_palworldsettings_s3 = true. Set to true if you would like to download an existing PalWorldSettings.ini to the server from a GitHub URL. Must also provide custom_palworldsettings_github_url = "https://my.url.com with a valid URL to a public GitHub repo.
custom_palworldsettings_github_url = "https://my.url.com A valid URL to a public GitHub repo to download an existing PalWorldSettings.ini from onto the server during startup. Must have custom_palworldsettings_github = true and use_custom_palworldsettings = true to use.
  • Using the S3 option will instruct terraform to create an S3 bucket along with an EC2 instance profile that will have permissions to assume an IAM role that is also created. This role contains a policy to allow only the EC2 instance to access the S3 bucket to download PalWorldSettings.ini. This also instructs the user_data script that runs when the server starts to download PalWorldSettings.ini from that S3 bucket and place it in /palworld-server/Pal/Saved/Config/LinuxServer/PalWorldSettings.ini

  • Using the GitHub option will simply instruct the user_data script that runs when the server starts to download PalWorldSettings.ini to the server and place it in /palworld-server/Pal/Saved/Config/LinuxServer/PalWorldSettings.ini

Starting From Existing Save Data, Restoring From Backups, or Migrating Servers

This guide outlines essential processes for starting from existing save data, restoring from backups, or migrating servers using this Terraform module. It emphasizes the importance of the DedicatedServerName setting and provides instructions for using both local and S3 bucket backups.

Prerequisites

Before proceeding with backup or restoration processes, you must obtain the DedicatedServerName value from your old Palworld server's GameUserSettings.ini file. This value is crucial as it corresponds to the directory name containing your .sav files on the old server.

[!DANGER] It is mandatory to provide the DedicatedServeName from the old Pal/Saved/Config/LinuxServer/GameUserSettings.ini file. This is also the name of the directory from the old server that contained your .sav files.

Note

Using this modules enable_s3_backups = true option will backup the GameUserSettings.ini file to S3 as well in the event the server is lost.

Using You Own S3 Bucket ( Bring Your Own )

Set backup_files_storage_type = "s3" if you have an AWS s3 bucket somewhere with the backups files already in it. Please note the warning below about the REQUIRED file structure of the bucket. Terraform and user_data are opinionated in how they retrieve and place these files, so you must adhere to this structure.

Warning

When backup_files_storage_type = "s3" using The objects in the S3 bucket must not be compressed and must be in the root of the S3 bucket. The bucket's file structure MUST match the picture below. It will be synced to the SaveGame/0/<dedicated_server_name> directory.

Required S3 Structure

Using Local Files

Set backup_files_storage_type = "local" if the save files are on your local host PC. Please note the warning below about the REQUIRED file structure of the bucket. Terraform and user_data are opinionated in how they retrieve and place these files, so you must adhere to this structure.

Warning

When backup_files_storage_type = "local" using The objects/files in the directory you specify with backup_files_local_path must not be compressed. Terraform will iterate through each file in that directory and upload it to the root of an S3 bucket it creates. It will do this for backup_files_local_path/Players as well.

Required local file structure

Required Local File Structure

  • backup_files_storage_type = "local" will instruct terraform to create an S3 bucket named palworld-bootstrap-local-saves-<region>-<accID> and upload the save files from your local PC backup_files_local_path directory specified to that bucket. The user_data script on the EC2 instance will download the files from that S3 bucket when the server starts and place them in the /palworld-server/Pal/Saved/SaveGames/0/<dedicated_server_name_hash> directory.

  • backup_files_storage_type = "s3" Is informing terraform that you have an existing S3 bucket somewhere that contains the save game data. The EC2 user_data script will attempt to sync the root of that S3 bucket with the SaveGames/0/<dedicated_server_name_hash> directory. It will also attempt to sync the S3 buckets Players folder to SaveGames/0/<dedicated_server_name_hash>/Players That is why it is important that the objects be uncompressed and in the proper structure.

Warning

When backup_files_storage_type = "local" using The objects/files in the directory you specify with backup_files_local_path must not be compressed. Terraform will iterate through each file in that directory and upload it to the root of an S3 bucket it creates.

Usage - Restore From Local Files

Relevant inputs:

  start_from_backup         = true
  backup_files_storage_type = "local"
  dedicated_server_name_hash = "FA8C44A6FA46436AAAE4D414C4214B25"
  backup_files_local_path   = "../../assets"

Usage - Restore From an Existing S3 Bucket ( Bring Your Own S3 Bucket)

Relevant inputs:

  start_from_backup         = true
  backup_files_storage_type = "s3"
  dedicated_server_name_hash = "FA8C44A6FA46436AAAE4D414C4214B25"
  existing_backup_files_bootstrap_bucket_arn  = "arn:aws:s3:::palworld-existing-s3-bucket-bootstrap"
  existing_backup_files_bootstrap_bucket_name = "palworld-existing-s3-bucket-bootstrap"
  • If start from backup = true then dedicated_server_name_hash is required

Using SSM Instead of SSH

AWS Systems Manager Session Manager is a web based way to connect to an instance from your browser instead of over SSH. It is more secure than enabling port 22 and SSH. Use the input enable_session_manaer = true to enable it.

Note

SSH and SSM can be used together is you wish.

Starting, Stopping, and Restarting Palworld

Action Command
Stop Palworld systemctl stop palworld
Start Palworld systemctl start palworld
Restart Palworld systemctl restart palworld

Updating Palworld

Palworld will update the next time the service is restarted with systemctl start palworld or systemctl restart palworld or if the server restarts.

Troubleshooting

  • Monitoring the installation - You can view the user_data script that ran by connecting to your server via SSH using the public key you provided, ubuntu user, and the IP address of the server. Example: ssh -i .\palworld_public_key ubuntu@34.225.216.87. Once on the server you can view the progress of the user_data script that installs and configures palworld using the command journalctl -xu cloud-final. Use the space bar to scroll through the output line by line or shift+g to scroll the end of the output. If there is an obvvious reason that palworld failed to install or start in the way you expect, you can most likely find it here.

  • Checking the palworld service is running - You can run systemctl status palworld to view the status of the palworld server. The service should say Active: active (running). If it does not, then the palworld server failed to start or has stopped for some reason.

Examples

Possible and Known Bugs

Memory leak? https://www.reddit.com/r/Palworld/comments/19bdsrn/dedicated_server_ram_usage/

Requirements

Name Version
terraform >= 1.5.0
aws >= 5.0.0

Providers

No providers.

Modules

Name Source Version
palworld_backup ./modules/backup n/a
palworld_compute ./modules/compute n/a
palworld_vpc ./modules/networking n/a

Resources

No resources.

Inputs

Name Description Type Default Required
active_unko Activate UNKO setting bool false no
admin_password Admin password string "RockwellSucks" no
ami_id The AMI ID to use. Not providing one will result in the latest version of Ubuntu Focal 20.04 being used string null no
auto_reset_guild_no_online_players Auto reset guild when no online players bool false no
auto_reset_guild_time_no_online_players Time for auto reset guild when no online players number 72 no
backup_files_local_path Path to existing save game files relative to your Terraform working directory. Will be uploaded to the server. Required if backup_files_storage_path = local string "" no
backup_files_storage_type The location of your save game files that you wish to start the server with. Supported options are local or s3'. localmeans the save game files exist somewhere on the host you are running terraform apply from.s3 means the files exist in an s3 bucket. string "local" no
backup_interval_cron_expression How often to backup the ShooterGame/Saved directory to S3 in cron expression format (https://crontab.cronhub.io/) string "0 23 * * *" no
backup_s3_bucket_arn The ARN of the s3 bucket that you would like to use for ShooterGame/Saved directory backups string "" no
backup_s3_bucket_name The name of the S3 bucket to backup the ShooterGame/Saved directory to string "" no
ban_list_url URL of the ban list string "https://api.palworldgame.com/api/banlist.txt" no
base_camp_max_num Maximum number of base camps number 128 no
base_camp_worker_max_num Maximum number of base camp workers number 15 no
build_object_damage_rate Build object damage rate number 1 no
build_object_deterioration_damage_rate Build object deterioration damage rate number 1 no
can_pickup_other_guild_death_penalty_drop Can players pick up other guild's death penalty drop bool false no
collection_drop_rate Collection drop rate number 1 no
collection_object_hp_rate Collection object HP rate number 1 no
collection_object_respawn_speed_rate Collection object respawn speed rate number 1 no
coop_player_max_num Maximum number of players in coop mode number 32 no
create_backup_s3_bucket True or False. Do you want to create an S3 bucket to FTP backups into bool false no
create_ssh_key True or False. Determines if an SSH key is created in AWS bool true no
custom_palworldsettings_github True or False. Set true if use_custom_palworldsettings is true and you want to download them from github. Must be a public repo. bool false no
custom_palworldsettings_github_url The URL to the PalWorldSettings.ini file on a public GitHub repo. Used when custom_palworldsettings_github and custom_game_usersettings both == true. string "" no
custom_palworldsettings_s3 True or False. Set true if use_custom_palworldsettings is true and you want to upload and download them from an S3 bucket during installation bool false no
day_time_speed_rate Day time speed rate number 1 no
death_penalty Death penalty setting. 0 = None : No lost, 1 = Item : Lost item without equipment, 2= ItemAndEquipment : Lost item and equipment, 3= All : Lost All item, equipment, pal(in inventory) number 1 no
dedicated_server_name_hash The DedicatedServerName= value from the old servers GameUserSettings.ini. Will be set on the new server to ensure data properly loads with backup data. string "" no
difficulty Game difficulty setting string "None" no
drop_item_alive_max_hours Maximum hours a drop item is alive number 1 no
drop_item_max_num Maximum number of drop items number 3000 no
drop_item_max_num_unko Maximum number of UNKO drop items number 100 no
ebs_volume_size The size of the EBS volume attached to the EC2 instance number 40 no
enable_aim_assist_keyboard Enable aim assist for keyboard bool false no
enable_aim_assist_pad Enable aim assist for pad bool true no
enable_defense_other_guild_player Enable defense against other guild players bool false no
enable_fast_travel Enable fast travel bool true no
enable_friendly_fire Enable friendly fire bool false no
enable_invader_enemy Enable invader enemy bool true no
enable_non_login_penalty Enable penalty for non-login bool true no
enable_player_to_player_damage Enable player to player damage bool false no
enable_rcon Is RCON enabled bool false no
enable_s3_backups True or False. Set to true to enable backing up of the ShooterGame/Saved directory to S3 bool false no
enable_session_manager True or False. Determines if SSM Session Manager is enabled or not bool false no
enable_ssh True or False. Determines if SSH and port 22 are enabled or not bool true no
enemy_drop_item_rate Enemy drop item rate number 1 no
exist_player_after_logout Does player exist in game after logout bool false no
existing_backup_files_bootstrap_bucket_arn The ARN of an existing S3 bucket with Palworld save game data. Files will be downloaded to the server. Objects must be in the root of the S3 bucket and not compressed. string "" no
existing_backup_files_bootstrap_bucket_name The Name of an existing S3 bucket with Palworld save game data. Files will be downloaded to the server. Objects must be in the root of the S3 bucket and not compressed. string "" no
existing_ssh_key_name The name of an EXISTING SSH key for use with the EC2 instance string null no
exp_rate Experience rate number 1 no
force_destroy True or False. Set to true if you want Terraform destroy commands to have the ability to destroy the backup bucket while it still containts backup files bool false no
guild_player_max_num Maximum number of players in a guild number 20 no
instance_type The instance type to use string "t3.large" no
is_multiplay Is the game in multiplay mode bool false no
is_pvp Is the game in PvP mode bool false no
is_start_location_select_by_map Is start location selected by map bool false no
night_time_speed_rate Night time speed rate number 1 no
pal_auto_hp_regen_rate Pal auto HP regeneration rate number 1 no
pal_auto_hp_regene_rate_in_sleep Pal auto HP regeneration rate in sleep number 1 no
pal_capture_rate Pal capture rate number 1 no
pal_damage_rate_attack Pal damage rate on attack number 1 no
pal_damage_rate_defense Pal damage rate on defense number 1 no
pal_egg_default_hatching_time Default hatching time for pal eggs number 72 no
pal_spawn_num_rate Pal spawn number rate number 1 no
pal_stamina_decrease_rate Pal stamina decrease rate number 1 no
pal_stomach_decrease_rate Pal stomach decrease rate number 1 no
palworldsettings_ini_path Path to PalWorldSettings.ini relative to your Terraform working directory. Will be uploaded to the server. Required if use_custom_palworldsettings = true and custom_game_usersettings_s3 = true. string "" no
player_auto_hp_regen_rate Player auto HP regeneration rate number 1 no
player_auto_hp_regen_rate_in_sleep Player auto HP regeneration rate in sleep number 1 no
player_damage_rate_attack Player damage rate on attack number 1 no
player_damage_rate_defense Player damage rate on defense number 1 no
player_stamina_decrease_rate Player stamina decrease rate number 1 no
player_stomach_decrease_rate Player stomach decrease rate number 1 no
public_ip Public IP address string "" no
public_port Public port number number 8211 no
rcon_port RCON port number number 27025 no
region Server region string "" no
s3_bucket_backup_retention Lifecycle rule. The number of days to keep backups in S3 before they are deleted number 7 no
server_description Server description string "Running On AWS" no
server_name Server name string "AWSWorldTest" no
server_password Server password string "RockwellSucks" no
server_player_max_num Maximum number of players on server number 32 no
ssh_ingress_allowed_cidr The CIDR range to allow SSH incoming connections from list(string)
[
"0.0.0.0/0"
]
no
ssh_key_name The name of the SSH key to be created for use with the EC2 instance string "palworld-ssh-key" no
ssh_public_key The path to the ssh public key to be used with the EC2 instance string "~/.ssh/palworld_public_key.pub" no
start_from_backup True of False. Set true to start the server from an existing palworld save. Requires existing save game files. bool false no
subnet_availability_zone The AZ of the subnet to be created within the VPC string "us-east-1a" no
subnet_cidr_block The CIDR block of the subnet to be created within the VPC string "10.0.1.0/24" no
use_auth Use authentication bool true no
use_custom_palworldsettings True or False. Set true if you want to provide your own PalWorldSettings.ini file when the server is started. Required if game_user_settings_ini_path is defined bool false no
vpc_cidr_block The CIDR block of the VPC to be created string "10.0.0.0/16" no
work_speed_rate Work speed rate number 1 no

Outputs

Name Description
backup_s3_bucket_name The Name of the S3 bucket created to store backups if enabled
custom_ini_s3_bucket_name The ID of the S3 bucket that was created if use custom ini with s3 was configured.
palworld_server_public_ip The public IP address of the Palworld server to connect on.
palworld_server_public_port The public port to connect to the Palworld serer on
palworldsettings_s3_content The contents of the palworldsettings.ini ( experimental ).
session_manager_enabled Is AWS SSM Session Manager enabled or not.