Create working directory Build your image Push your image

Prepare a container image with your game server software

This documentation is for a feature that is in public preview release. It is subject to change.

The container is the most basic element of an Amazon GameLift container fleet. Your container includes your game server, along with with its dependencies such as SDKs, software, directories, and files.

To function in a container fleet, your game server must run on Linux, and be integrated with server SDK 5.x.

Set up your working directory

Your working directory is where you put all the files you need to build your container image and define how Amazon GameLift runs it.

To set up your container working directory

Create the directory where you want to work with your Amazon GameLift container images.
For example:
```
[~/]$ mkdir -p work/glc/gamebuild && cd work && find .
.
./glc
./glc/gamebuild
```

Clone the Amazon GameLift Agent.

For example:


[~/work]$ git clone https://github.com/aws/amazon-gamelift-agent.git 
Cloning into 'amazon-gamelift-agent'...

Build the GameLiftAgent using Maven.

For example:


[~/work]$ cd amazon-gamelift-agent


[~/work/amazon-gamelift-agent]$ mvn clean compile assembly:single && \
mv target ../glc && cd .. && find glc

Add a game server that's been integrated with server SDK 5.x, built, and packaged into a .ZIP file.
Copy your .ZIP file to ~/work/glc/gamebuild/.

If you don't have an SDK 5.x game server, then you can download and use our sample SimpleServer game to try using a container fleet.


[~/work]$ curl -o glc/gamebuild/SimpleServer.zip \ 
'https://ws-assets-prod-iad-r-iad-ed304a55c2ca1aee.s3.us-east-1.amazonaws.com/086bb355-4fdc-4e63-8ca7-af7cfc45d4f2/AmazonGameLiftSampleServerBinary.zip' && 
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100 5140k  100 5140k    0     0  12.3M      0 --:--:-- --:--:-- --:--:-- 12.3M
glc
glc/target
glc/target/GameLiftAgent-1.0.jar
glc/gamebuild
glc/gamebuild/SimpleServer.zip

Build your container image

Your Dockerfile specifies the environment, software, and instructions to build your container.

To create your Dockerfile

Move into the glc subdirectory.


[~/work]$ cd glc && find 

.
./target
./target/GameLiftAgent-1.0.jar
./gamebuild

Create and open a new Dockerfile.
For example:
```
[~/work/glc]$ nano Dockerfile
```
Copy from one of the following templates, and then paste the content into your Dockerfile.

This template contains the minimum instructions that a container needs to usable in an Amazon GameLift fleet. Modify the content as needed for your game server.


# Base image
# ----------
  # Add the base image that you want to use over here,
  # Make sure to use an image with the same architecture as the
  # Instance type you are planning to use on your fleets.
  # We require JDK to be installed in the base image, so that
  # it can be used to run the &AGS; Agent
FROM public.ecr.aws/amazoncorretto/amazoncorretto:17-amd64
  #
# Game build directory
# --------------------
  # Add your game build to gamebuild directory and add the zip file name in the 'GAME_BUILD_ZIP' env variable below.
  # The game build provided over here needs to be integrated with gamelift server sdk.
  # This template assumes that the game build is in a zip format.
ENV GAME_BUILD_ZIP="<ADD_GAME_BUILD_ZIP_FILE_NAME>" \
  #
# Default directory
# -----------------
  # Default directory, the value provided here should be where the game executable exists.
  # Provide this same value as your launch path in RuntimeConfiguration when creating a fleet.
  # Ref: https://docs.aws.amazon.com/gamelift/latest/apireference/API_ServerProcess.html
GAME_EXECUTABLE="<ADD NAME OF EXECUTABLE WITHIN THE GAME BUILD>" \
HOME_DIR="/local/game" \
  #
  # Registered compute in anywhere fleet (not used in container fleets)
  # -------------------------------------------------------------------
  # Add the name for the registered compute in an anywhere fleet.
  # This environment variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
  GAMELIFT_COMPUTE_NAME="<ADD_COMPUTE_NAME>" \
  #
# Default Gamelift Agent jar
# --------------------------
GAMELIFT_AGENT_EXEC="GameLiftAgent-1.0.jar" \
  #
  # This env variable defines the name of the S3 bucket that stores the GameLift Agent logs.
  # This S3 bucket should exist in the customer AWS account.
  # In order to allow GameLift agent to upload logs to this s3 bucket, customers would need to
  # include s3:PutObject permission in the IAM role provided as instanceRoleArn during CreateFleet operation.
GAMELIFT_AGENT_LOGS_BUCKET_NAME="<ADD NAME OF GAMELIFT AGENT LOGS S3 BUCKET>" \
  #
# -----------
  # This env variable defines the name of the S3 bucket that stores the game session logs.
  # This S3 bucket should exist in the customer AWS account.
  # In order to allow GameLift agent to upload logs to this s3 bucket, customers would need to
  # include s3:PutObject permission in the IAM role provided as instanceRoleArn during CreateFleet operation.
# -----------
GAME_SESSION_LOGS_BUCKET_NAME="<ADD NAME OF GAME SESSION LOGS S3 BUCKET>" \
#
# -----------
GAMELIFT_AGENT_LOGS_PATH="/local/game/agentlogs/" \
  #
# NOT USED in container fleets - USED in Anywhere fleets
# ----------------------------------------------------------
  # Specifiy the type of compute resource used to host the game servers.
  # This env variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
#
# -----------
COMPUTE_TYPE="ANYWHERE" \
  #
  # Specify the credential to be used for creating the client.
  # This env variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
#
# -----------
CREDENTIAL_PROVIDER="environment-variable"

USER root

    # intall dependencies as necessary
    RUN yum install -y sudo \
                        unzip \
                        git \
                        shadow-utils \
                        iputils \
                        tar \
                        gcc \
                        make \
                        openssl-devel \
                        zlib-devel \
                        vim \
                        net-tools \
                        nc \
                        procps
    
    # Set up the ground for 'gamescale' user
    RUN groupadd -r gamescale -g 500 && \
      useradd -u 500 -r -g gamescale -m -s /sbin/nologin -c "Gamescale user" gamescale && \
      echo "gamescale ALL=(ALL) NOPASSWD: ALL" | (EDITOR="tee -a" visudo) && \
      mkdir -p $HOME_DIR && \
      mkdir $HOME_DIR/mono && \
      chown -R gamescale:gamescale $HOME_DIR
    
    WORKDIR $HOME_DIR
    
    # extract game build as necessary
    COPY ./gamebuild/$GAME_BUILD_ZIP .
    RUN unzip ./$GAME_BUILD_ZIP -d ./
    
    # copy Gamelift Agent jar
    COPY ./gameliftAgent/$GAMELIFT_AGENT_EXEC ./
    
    # Add permissions to game build and gamelift agent jar
    RUN chmod +x ./$GAME_EXECUTABLE
    RUN chmod +x ./$GAMELIFT_AGENT_EXEC
    
    # Check if java is installed on the image, if not then the Agent will not be able to run
    RUN java --version
    
    USER gamescale
    
    ENV PATH="$PATH:$HOME_DIR/bin:$JAVA_HOME"
    
    # Change directory to bin
    WORKDIR $HOME_DIR
    
    # check path before starting the container
    RUN echo $PATH
    
    # Create logs directory for GameLift Agent & server processes
    RUN mkdir logs
    RUN mkdir agentlogs
    
    # Start the GameLift Agent
    ENTRYPOINT sleep 90 && java -jar $GAMELIFT_AGENT_EXEC -ip "192.168.1.1" -gslb "$GAME_SESSION_LOGS_BUCKET_NAME" -galb "$GAMELIFT_AGENT_LOGS_BUCKET_NAME" -galp "$GAMELIFT_AGENT_LOGS_PATH" -glc environment-variable


# Base image
# ----------
  # Add the base image that you want to use over here,
  # Make sure to use an image with the same architecture as the
  # Instance type you are planning to use on your fleets.
  # We require JDK to be installed in the base image, so that
  # it can be used to run the &AGS; Agent
FROM public.ecr.aws/amazoncorretto/amazoncorretto:17-amd64
  #
# Game build directory
# --------------------
  # Add your game build to gamebuild directory and add the zip file name in the 'GAME_BUILD_ZIP' env variable below.
  # The game build provided over here needs to be integrated with gamelift server sdk.
  # This template assumes that the game build is in a zip format.
ENV GAME_BUILD_ZIP="SimpleServer.zip" \
  #
# Default directory
# -----------------
  # Default directory, the value provided here should be where the game executable exists.
  # Provide this same value as your launch path in RuntimeConfiguration when creating a fleet.
  # Ref: https://docs.aws.amazon.com/gamelift/latest/apireference/API_ServerProcess.html
GAME_EXECUTABLE="GameLiftSampleServer" \
HOME_DIR="/local/game" \
  #
  # Registered compute in anywhere fleet (not used in container fleets)
  # -------------------------------------------------------------------
  # Add the name for the registered compute in an anywhere fleet.
  # This environment variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
  GAMELIFT_COMPUTE_NAME="<ADD_COMPUTE_NAME>" \
  #
# Default Gamelift Agent jar
# --------------------------
GAMELIFT_AGENT_EXEC="GameLiftAgent-1.0.jar" \
  #
  # This env variable defines the name of the S3 bucket that stores the GameLift Agent logs.
  # This S3 bucket should exist in the customer AWS account.
  # In order to allow GameLift agent to upload logs to this s3 bucket, customers would need to
  # include s3:PutObject permission in the IAM role provided as instanceRoleArn during CreateFleet operation.
GAMELIFT_AGENT_LOGS_BUCKET_NAME="<ADD NAME OF GAMELIFT AGENT LOGS S3 BUCKET>" \
  #
# -----------
  # This env variable defines the name of the S3 bucket that stores the game session logs.
  # This S3 bucket should exist in the customer AWS account.
  # In order to allow GameLift agent to upload logs to this s3 bucket, customers would need to
  # include s3:PutObject permission in the IAM role provided as instanceRoleArn during CreateFleet operation.
# -----------
GAME_SESSION_LOGS_BUCKET_NAME="<ADD NAME OF GAME SESSION LOGS S3 BUCKET>" \
#
# -----------
GAMELIFT_AGENT_LOGS_PATH="/local/game/agentlogs/" \
  #
# NOT USED in container fleets - USED in Anywhere fleets
# ----------------------------------------------------------
  # Specifiy the type of compute resource used to host the game servers.
  # This env variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
#
# -----------
COMPUTE_TYPE="ANYWHERE" \
  #
  # Specify the credential to be used for creating the client.
  # This env variable is required only for anywhere fleets, but not for container fleets.
  # If it is set for container fleets, it will be overridden by Gamelift.
#
# -----------
CREDENTIAL_PROVIDER="environment-variable"

USER root

    # intall dependencies as necessary
    RUN yum install -y sudo \
                        unzip \
                        git \
                        shadow-utils \
                        iputils \
                        tar \
                        gcc \
                        make \
                        openssl-devel \
                        zlib-devel \
                        vim \
                        net-tools \
                        nc \
                        procps
    
    # Set up the ground for 'gamescale' user
    RUN groupadd -r gamescale -g 500 && \
      useradd -u 500 -r -g gamescale -m -s /sbin/nologin -c "Gamescale user" gamescale && \
      echo "gamescale ALL=(ALL) NOPASSWD: ALL" | (EDITOR="tee -a" visudo) && \
      mkdir -p $HOME_DIR && \
      mkdir $HOME_DIR/mono && \
      chown -R gamescale:gamescale $HOME_DIR
    
    WORKDIR $HOME_DIR
    
    # extract game build as necessary
    COPY ./gamebuild/$GAME_BUILD_ZIP .
    RUN unzip ./$GAME_BUILD_ZIP -d ./
    
    # copy Gamelift Agent jar
    COPY ./target/$GAMELIFT_AGENT_EXEC ./
    
    # Add permissions to game build and gamelift agent jar
    RUN chmod +x ./$GAME_EXECUTABLE
    RUN chmod +x ./$GAMELIFT_AGENT_EXEC
    
    # Check if java is installed on the image, if not then the Agent will not be able to run
    RUN java --version
    
    USER gamescale
    
    ENV PATH "$PATH:$HOME_DIR/bin:$JAVA_HOME"
    
    # Change directory to bin
    WORKDIR $HOME_DIR
    
    # check path before starting the container
    RUN echo $PATH
    
    # Create logs directory for GameLift Agent & server processes
    RUN mkdir logs
    RUN mkdir agentlogs
    
    # Start the GameLift Agent
    ENTRYPOINT sleep 90 && java -jar $GAMELIFT_AGENT_EXEC -ip "192.168.1.1" -gslb "$GAME_SESSION_LOGS_BUCKET_NAME" -galb "$GAMELIFT_AGENT_LOGS_BUCKET_NAME" -galp "$GAMELIFT_AGENT_LOGS_PATH" -glc environment-variable

Note

Note: Some of the environment variables in the Dockerfile can be overridden by the ContainerDefinition.

To build your container image

Build your container image.
If you're using your own SDK 5.x server
You can specify whatever local repository name you want.
[~/work/glc]$ docker build -t <local repository name>:<optional tag> .
If you're using our SimpleServer sample
[~/work/glc]$ docker build -t simple-server:version-1 . Successfully built 0123456789012 Successfully tagged simple-server:version-1
Note
In following examples, we use simpler-server as the initial REPOSITORY value, and version-1 as the TAG value.

View the list of images and make note of the REPOSITORY and IMAGE ID values. You'll need them in a procedure below.


[~/work/glc]$ docker images
REPOSITORY       TAG          IMAGE ID        CREATED           SIZE
simple-server    version-1    0123456789012    14 minutes ago    1.24GB

Push your container image to Amazon ECR

Upload your container image to a private repository in Amazon ECR. When you create a container group definition, you reference this repository location so that Amazon GameLift can take a snapshot of your container image and use it when deploying a container fleet.

Note

If you don't yet have an Amazon ECR private repository, then create one.

To get your Amazon ECR credentials

Before you can push your container image to Amazon ECR, you must acquire your AWS credentials in temporary form and provide them to Docker. Get your Amazon ECR credentials so that Docker can 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

To push your container image to Amazon ECR

Copy the URI of the Amazon ECR private repository you want to use.

Apply an Amazon ECR tag to your container image.


[~/work/glc]$ docker tag <IMAGE ID from above> <Amazon ECR private repository URI>:<optional tag>

Push your container image to Amazon ECR


[~/work/glc]$ docker image push  <Amazon ECR private repository URI>

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Integrate your game with Amazon GameLift

Design a container fleet