# Package a game server build for deployment Get your game server software ready for deployment on your hosting resources. Once deployed, the software is installed on each hosting resource, and then one or more game server process is launched and readied to host game sessions for players. Getting a game server build ready varies depending on the type of Amazon GameLift Servers hosting options you're using. All game server builds must be integrated with the server SDK for Amazon GameLift Servers, as described in [Integrate a game server with Amazon GameLift Servers](gamelift-sdk-server.md). The topics in this section provide guidance on how to get your software ready for deployment to the following scenarios. + For managed EC2 hosting, package your server software and upload it to Amazon GameLift Servers for deployment. + For managed containers hosting, build a container image with your server software and store it in Amazon Elastic Container Registry for deployment. + For hosting with Amazon GameLift Servers Anywhere, package your server software as needed for installation on your own hosting resources. **Note** If you're deploying an Amazon GameLift Servers Realtime configured script, see [ Upload a script for Amazon GameLift Servers Realtime](https://docs.aws.amazon.com/gameliftservers/latest/realtimeguide/realtime-script-uploading.html). **Topics** + [Create a game server build for Amazon GameLift Servers](gamelift-build-cli-uploading.md) + [Build a container image for Amazon GameLift Servers](containers-prepare-images.md) # Create a game server build for Amazon GameLift Servers After you integrate your game server with Amazon GameLift Servers (see [Prepare a game for hosting with Amazon GameLift Servers](integration-intro.md)), install the game server software onto your compute resources for hosting. This process varies depending on the type of Amazon GameLift Servers hosting you're using. ## Deploy for managed hosting If you're using Amazon GameLift Servers managed EC2 hosting, you must package your game server software and upload it to Amazon GameLift Servers. When you create a managed fleet, Amazon GameLift Servers automatically deploys it to each fleet instance. The topics in this section describe how to package your build files for uploading, create an optional build install script, and then upload the files using the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/) or AWS SDK. ## Deploy for Anywhere hosting If you're using Amazon GameLift Servers Anywhere fleets for self-managed hosting, it's your responsibility to install the game server software onto each compute in a fleet and keep it updated. When an integrated game server process starts running, it automatically initializes and establishes communication with the Amazon GameLift Servers service. The server process starts game sessions from prompts by Amazon GameLift Servers and reports activity back to the service. **Topics** + [Deploy for managed hosting](#gamelift-build-custom-upload) + [Deploy for Anywhere hosting](#gamelift-build-custom-anywhere) + [Package your game build files](gamelift-build-packaging.md) + [Add a build install script](gamelift-build-cli-uploading-install.md) + [Create an Amazon GameLift Servers build resource for managed hosting](gamelift-build-cli-uploading-builds.md) # Package your game build files Before uploading your configured game server to Amazon GameLift Servers, package the game build files into a build directory. This process is a requirement when hosting with an EC2 managed fleet, and is a best practice when hosting with an Anywhere fleet. The build directory should include all the components that are required to run your game servers and host game sessions. This might include the following: + **Game server binaries** – The binary files required to run the game server. A build can include binaries for multiple game servers built to run on the same platform. For a list of supported platforms, see [Get Amazon GameLift Servers development tools](gamelift-supported.md). + **Dependencies** – Any dependent files that your game server executables require to run. Examples include assets, configuration files, and dependent libraries. **Note** For game builds created with the server SDK for Amazon GameLift Servers for C\$1\$1 (including those created with the Unreal plugin), include the OpenSSL DLL for the same version of OpenSSL that you built the server SDK with. See the server SDK README file for more details. + **Install script** (Optional) – A script file to handle tasks that install your game build on Amazon GameLift Servers hosting servers. Place this file at the root of the build directory. Amazon GameLift Servers runs the install script as part of fleet creation. You can set up any application in your build, including your install script, to access your resources securely on other AWS services. For information about ways to do this, see [Connect your Amazon GameLift Servers hosted game server to other AWS resources](gamelift-sdk-server-resources.md). After you've packaged your build files, make sure that your game server can run on a clean installation of your target OS to verify that all required dependencies are included and that your install script is accurate. # Add a build install script Create an install script for the operating system (OS) of your game build: + Windows: Create a batch file named `install.bat`. + Linux: Create a shell script file named `install.sh`. When creating an install script, keep in mind the following: + The script can't take any user input. + Amazon GameLift Servers installs the build and recreates the file directories in your build package on a hosting server in the following locations: + Windows fleets: `C:\game` + Linux fleets: `/local/game` + During the installation process for Linux fleets, the run-as user has limited access to the instance file structure. This user has full rights to the directory where your build files are installed. If your install script performs actions that require administrator permissions, then specify admin access using **sudo**. The run-as user for Windows fleets has administrator permissions by default. Permission failures related to the install script generate an event message that indicates a problem with the script. + On Linux, Amazon GameLift Servers supports common shell interpreter languages such as bash. Add a shebang (such as `#!/bin/bash`) to the top of your install script. To verify support for your preferred shell commands, remotely access an active Linux instance and open a shell prompt. For more information, see [Connect to fleet instances](fleets-remote-access.md). + The install script can't rely on a VPC peering connection. A VPC peering connection isn't available until after Amazon GameLift Servers installs the build on fleet instances. **Example Windows install bash file** This example `install.bat` file installs Visual C\$1\$1 runtime components required for the game server and writes the results to a log file. The script includes the component file in the build package at the root. ``` vcredist_x64.exe /install /quiet /norestart /log c:\game\vcredist_2013_x64.log ``` **Example Linux install shell script** This example `install.sh` file uses bash in the install script and writes results to a log file. ``` #!/bin/bash echo 'Hello World' > install.log ``` This example `install.sh` file shows how you can use the Amazon CloudWatch agent to collect system-level and custom metrics, and handle log rotation. Because Amazon GameLift Servers runs in a service VPC, you must grant Amazon GameLift Servers permissions to assume an AWS Identity and Access Management (IAM) role on your behalf. To allow Amazon GameLift Servers to assume a role, create a role that includes the AWS managed policy `CloudWatchAgentAdminPolicy`, and use that role when you create a fleet. ``` sudo yum install -y amazon-cloudwatch-agent sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm sudo yum install -y collectd cat <<'EOF' > /tmp/config.json { "agent": { "metrics_collection_interval": 60, "run_as_user": "root", "credentials": { "role_arn": "arn:aws:iam::account#:role/rolename" } }, "logs": { "logs_collected": { "files": { "collect_list": [ { "file_path": "/tmp/log", "log_group_name": "gllog", "log_stream_name": "{instance_id}" } ] } } }, "metrics": { "namespace": "GL_Metric", "append_dimensions": { "ImageId": "${aws:ImageId}", "InstanceId": "${aws:InstanceId}", "InstanceType": "${aws:InstanceType}" }, "metrics_collected": { // Configure metrics you want to collect. // For more information, see [Manually create or edit the CloudWatch agent configuration file](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html). } } } EOF sudo mv /tmp/config.json /opt/aws/amazon-cloudwatch-agent/bin/config.json sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json sudo systemctl enable amazon-cloudwatch-agent.service ``` # Create an Amazon GameLift Servers build resource for managed hosting When creating a build and uploading your files, you have a couple of options: + [Create a build from a file directory](gamelift-build-cli-uploading-upload-build.md). This is the simplest and most commonly used option. + [Create a build with files in Amazon Simple Storage Service (Amazon S3)](gamelift-build-cli-uploading-create-build.md). With this option, you can manage your build versions in Amazon S3. With both methods, Amazon GameLift Servers creates a new build resource with a unique build ID and other metadata. The build starts in the **Initialized** status. After Amazon GameLift Servers acquires the game server files, the build moves to **Ready** status. When the build is ready, you can deploy it to a new Amazon GameLift Servers fleet. For more information, see [Create an Amazon GameLift Servers managed EC2 fleet](fleets-creating.md).When Amazon GameLift Servers sets up the new fleet, it downloads the build files to each fleet instance and installs the build files. # Create a build from a file directory To create a game build stored in any location, including a local directory, use the [https://docs.aws.amazon.com/cli/latest/reference/gamelift/upload-build.html](https://docs.aws.amazon.com/cli/latest/reference/gamelift/upload-build.html) AWS CLI command. This command creates a new build record in Amazon GameLift Servers and uploads files from a location that you specify. **Send an upload request.** In a command line window, enter the following **upload-build** command and parameters. ``` aws gamelift upload-build \ --name user-defined name of build \ --operating-system supported OS \ --server-sdk-version server SDK for Amazon GameLift Servers version \ --build-root build path \ --build-version user-defined build number \ --region region name ``` + **operating-system** – The game server build's runtime environment. You must specify an OS value. You can't update this later. + **server-sdk-version** – The version of the Amazon GameLift Servers server SDK that your game server is integrated with. If you don't provide a value, Amazon GameLift Servers uses the default value `4.0.2`. If you specify an incorrect server SDK version, the game server build might fail when calling `InitSdk` to establish a connection to the Amazon GameLift Servers service. + **build-root** – The directory path of your build files. + **name** – A descriptive name for the new build. + **build-version** – The version details for the build files. + **region** – The AWS Region where you want to create your build. Create the build in the Region where you plan to deploy fleets. If you're deploying your game in multiple Regions, create a build in each Region. **Note** View your current default Region using the [https://docs.aws.amazon.com/cli/latest/reference/configure/get.html](https://docs.aws.amazon.com/cli/latest/reference/configure/get.html). To change your default Region, use the [https://docs.aws.amazon.com/cli/latest/reference/configure/set.html](https://docs.aws.amazon.com/cli/latest/reference/configure/set.html) command. *Examples* ``` aws gamelift upload-build \ --operating-system AMAZON_LINUX_2023 \ --server-sdk-version "5.0.0" \ --build-root "~/mygame" \ --name "My Game Nightly Build" \ --build-version "build 255" \ --region us-west-2 ``` ``` aws gamelift upload-build \ --operating-system WINDOWS_2022 \ --server-sdk-version "5.0.0" \ --build-root "C:\mygame" \ --name "My Game Nightly Build" \ --build-version "build 255" \ --region us-west-2 ``` In response to your upload request, Amazon GameLift Servers provides upload progress. On a successful upload, Amazon GameLift Servers returns the new build record ID. Upload time depends on the size of your game files and the connection speed. # Create a build with files in Amazon S3 You can store your build files in Amazon S3 and upload them to Amazon GameLift Servers from there. When you create your build, you specify the S3 bucket location, and Amazon GameLift Servers retrieves the build files directly from Amazon S3. **To create a build resource** 1. **Store your build files in Amazon S3.** Create a .zip file containing the packaged build files and upload it to an S3 bucket in your AWS account. Take note of the bucket label and the file name, you'll need these when creating an Amazon GameLift Servers build. 1. **Give Amazon GameLift Servers access to your build files.** Create an IAM role by following the instructions in [Access a game build file in Amazon S3](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-storage-loc). After you've created the role, take note of the new role's Amazon Resource Name (ARN), you'll need this when creating a build. 1. **Create a build.** Use the Amazon GameLift Servers console or the AWS CLI to create a new build record. You must have the `PassRole` permission, as described in [IAM permission examples for Amazon GameLift Servers](gamelift-iam-policy-examples.md). ------ #### [ Console ] 1. In the [Amazon GameLift Servers console](https://console.aws.amazon.com/gamelift/), in the navigation pane, choose **Hosting**, **Builds**. 1. On the **Builds** page, choose **Create build**. 1. On the **Create build** page, under **Build settings**, do the following: 1. For **Name**, enter a script name. 1. For **Version**, enter a version. Because you can update the content of a build, version data can help you track updates. 1. For **Operating system (OS)**, choose the OS of your game server build. You can't update this value later. 1. For **Game server build**, enter the **S3 URI** of the build object that you uploaded to Amazon S3, and choose the **Object version**. If you don't remember the Amazon S3 URI and object version, choose **Browse S3** and search for the build object. 1. For **IAM role**, choose the role that you created that gives Amazon GameLift Servers access to your S3 bucket and build object. 1. (Optional) Under **Tags**, add tags to the build by entering **Key** and **Value** pairs. 1. Choose **Create**. Amazon GameLift Servers assigns an ID to the new build and uploads the designated .zip file. You can view the new build, including the status, on the **Builds** page. ------ #### [ AWS CLI ] To define the new build and upload your server build files, use the [https://docs.aws.amazon.com/cli/latest/reference/gamelift/create-build.html](https://docs.aws.amazon.com/cli/latest/reference/gamelift/create-build.html) command. 1. Open a command line window and switch to a directory where you can use the AWS CLI. 1. Enter the following **create-build** command: ``` aws gamelift create-build \ --name user-defined name of build \ --server-sdk-version server SDK for Amazon GameLift Servers version \ --operating-system supported OS \ --build-version user-defined build number \ --storage-location "Bucket"=S3 bucket label,"Key"=Build .zip file name,"RoleArn"=Access role ARN} \ --region region name ``` + **name** – A descriptive name for the new build. + **server-sdk-version** – The version of the server SDK for Amazon GameLift Servers you used to integrate your game server with Amazon GameLift Servers. If you don't provide a value, Amazon GameLift Servers uses the default value `4.0.2`. + **operating-system** – The game server build's runtime environment. You must specify an OS value. You can't update this later. + **build-version** – The version details for the build files. This information can be useful because each new version of your game server requires a new build resource. + **storage-location** + **Bucket** – The name of the S3 bucket that contains your build. For example, "my\$1build\$1files". + **Key** – The name of the .zip file that contains your build files. For example, "my\$1game\$1build\$17.0.1, 7.0.2". + **RoleARN** – The ARN assigned to the IAM role that you created. For example, "arn:aws:iam::111122223333:role/GameLiftAccess". For an example policy, see [Access a game build file in Amazon S3](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-access-storage-loc). + **region** – Create the build in the AWS Region where you plan to deploy fleets. If you're deploying your game in multiple Regions, create a build in each Region. **Note** We recommend checking your current default Region using the [https://docs.aws.amazon.com/cli/latest/reference/configure/get.html](https://docs.aws.amazon.com/cli/latest/reference/configure/get.html) command[https://docs.aws.amazon.com/cli/latest/reference/configure/get.html](https://docs.aws.amazon.com/cli/latest/reference/configure/get.html). To change your default Region, use the [https://docs.aws.amazon.com/cli/latest/reference/configure/set.html](https://docs.aws.amazon.com/cli/latest/reference/configure/set.html) command. *Example* ``` aws gamelift create-build \ --operating-system WINDOWS_2022 \ --storage-location "Bucket"="my_game_build_files","Key"="mygame_build_101.zip","RoleArn"="arn:aws:iam::111122223333:role/gamelift" \ --name "My Game Nightly Build" \ --build-version "build 101" \ --region us-west-2 ``` 1. To view the new build, use the [https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-build.html](https://docs.aws.amazon.com/cli/latest/reference/gamelift/describe-build.html) command. ------ # Build a container image for Amazon GameLift Servers This topic describes how to create a container image with your game server software to use with Amazon GameLift Servers. A game server container image includes the game server executable and any dependencies it needs to run. Game server container images are used with an Amazon GameLift Servers managed containers hosting solution. For details on building the complete solution, see: + [Development roadmap for hosting with Amazon GameLift Servers managed containers](gamelift-roadmap-containers.md) + [How containers work in Amazon GameLift Servers](containers-howitworks.md) Complete the following tasks to get your game server container image ready for deployment to an Amazon GameLift Servers container fleet. Before starting these tasks, finish integrating your game server code with the Amazon GameLift Servers server SDK. **Topics** + [Create a game server container image](#containers-prepare-images-build) + [Push a container image to Amazon ECR](#containers-prepare-images-upload) ## Create a game server container image Follow these instructions while working on a Linux-based platform or using Windows Subsystem for Linux (WSL) with Docker installed. **To create a game server container image** 1. Prepare a working directory with your game server software. On a local machine, create a working directory to organize the files for your game server container. Your container image uses this file structure when deploying the container to Amazon GameLift Servers resources for hosting. For example: ``` [~/]$ mkdir -p work/glc/gamebuild && cd work && find . . ./glc ./glc/gamebuild ``` **Note** If you're trying out this feature and don't have a working game server build yet, try our sample game server, [SimpleServer](https://github.com/aws-solutions-library-samples/guidance-for-custom-game-backend-hosting-on-aws/tree/main/BackendFeatures/AmazonGameLiftIntegration/SimpleServer), which is available on GitHub. 1. Create a new Dockerfile using the template provided. 1. Follow the instructions in the Dockerfile template to update it for your own use. + Update the base image as needed. + Set environment variables for your game server build. 1. Build the container image. Run the `docker build`, specifying your own repository name. For example: ``` [~/work/glc]$ docker build -t : . ``` You can view your repositories and images IDs using the `docker images` command, as illustrated in this example: ## Dockerfile template for a game server container image This template contains the minimum instructions that a game server container needs to usable in an Amazon GameLift Servers fleet. Modify the content as needed for your game server. ``` # Base image # ---------- # Add the base image that you want to use, # Make sure to use an image with the same architecture as the # Instance type you are planning to use on your fleets. FROM public.ecr.aws/amazonlinux/amazonlinux # # Game build directory # -------------------- # Add your gamebuild directory to the env variable below. # The game build provided here needs to be integrated with server sdk for Amazon GameLift Servers. ENV GAME_BUILD_DIRECTORY="" \ # # Game executable and launch parameters # --------------- # Add the relative path to your executable in the 'GAME_EXECUTABLE' env variable below. # The game build provided over here needs to be integrated with server sdk for Amazon GameLift Servers. # This template assumes that the executable path is relative to the game build directory. # Add any launch parameters to pass into your executable in the 'LAUNCH_PARAMS' env variable below. # Add 'HOME_DIR' to identify where the game executable and logs exist. GAME_EXECUTABLE="" \ LAUNCH_PARAMS= \ HOME_DIR="/local/game" \ # Install dependencies as necessary RUN yum install -y shadow-utils RUN mkdir -p $HOME_DIR COPY ./$GAME_BUILD_DIRECTORY/ $HOME_DIR # Change directory to home WORKDIR $HOME_DIR # Set up for 'gamelift' user RUN useradd -m gamelift && \ echo "gamelift ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers && \ chown -R gamelift:gamelift $HOME_DIR # Add permissions to game build RUN chmod +x ./$GAME_EXECUTABLE USER gamelift # Check directory before starting the container RUN ls -lhrt . # Check path before starting the container RUN echo $PATH # Start the game build ENTRYPOINT ["/bin/sh", "-c", "./$GAME_EXECUTABLE", "$LAUNCH_PARAMS"] ``` ## Push a container image to Amazon ECR After you've created a container image for deployment to Amazon GameLift Servers, store the image In a public or private repository in Amazon ECR. This repository is assigned a URI value, which Amazon GameLift Servers uses to take a snapshot of the image for deployment to a container fleet. **Note** If you don't yet have an Amazon ECR private repository, then [create one](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html). **To push your container image to Amazon ECR** 1. Get your Amazon ECR credentials. Before pushing a container image to Amazon ECR, first acquire your AWS credentials in temporary form and provide them to Docker. Docker needs these credentials to log in. ``` [~/work/glc]$ aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.us-west-2.amazonaws.com WARNING! Your password will be stored unencrypted in /home/user-name/.docker/config.json. Configure a credential helper to remove this warning. See https://docs.docker.com/engine/reference/commandline/login/#credentials-store Login Succeeded ``` 1. Copy the URI of the [Amazon ECR private repository](https://console.aws.amazon.com/ecr/private-registry/repositories) you want to use. 1. Apply an Amazon ECR tag to your container image. **Example** ``` [~/work/glc]$ docker tag : ``` 1. Push your container image to Amazon ECR **Example** ``` [~/work/glc]$ docker image push ```