Dependencies

• Signing up to the Metaplay Portal - To be able to deploy a game server to the Metaplay Cloud, you need to set up an organization, project, and environment for a game in the Metaplay Portal. Your user also needs the game-admin role for the environment.
• Having the required tools installed on your system - To follow the steps provided you need: AWS CLI, Docker, Helm, and jq.

Overview

This guide provides step-by-step instructions for manually building and deploying your game server into a Metaplay-managed environment.

Instead of manually building and deploying the server, you should consider setting up a CI to do this task automatically. See the Setup CI to Deploy a Game Server to the Metaplay-Managed Cloud guide for instructions.

Installing the metaplay-auth Command Line Tool

We provide a command line tool to help you obtain the required credentials as well as to easily fetch relevant details required for building, pushing, and deploying a game server to the cloud.

Installing from NPM

We provide metaplay-auth as an NPM package under the @metaplay organization. You can install the package globally with:

npm install -g @metaplay/metaplay-auth

Alternatively, if you just want to run commands with the latest metaplay-auth version, you can leverage npx:

npx @metaplay/metaplay-auth@latest -V

Using the metaplay-auth Tool

The metaplay-auth tool serves a couple of different, important functions:

1. It allows you to log into your Metaplay account and obtain associated tokens for interacting with different Metaplay APIs.
2. It allows you to obtain ephemeral Kubernetes and AWS credentials for your game server environments, which are needed for pushing images and deploying game servers.
3. It provides easy access to the details of your environments, which you'll need for pushing images.

To use the tool, you should first log in:

metaplay-auth login

This will pop up a browser and allow you to log in using your Metaplay identity. The tokens and the session are by default valid for an hour, after which you'll need to log in again to obtain fresh tokens. If you want to end your session earlier, you can invoke the logout command, which will remove your tokens. Otherwise, the tokens automatically expire after the validity period.

Build the Server Docker Image

Create a unique docker image tag for this particular build. You must use unique tags for each build! The current timestamp is used here, but in a CI job, you should use the git commit hash or similar instead.

export IMAGE_TAG=$(date +%s)

Next, build the docker image:

docker build --platform linux/amd64 -f MetaplaySDK/Dockerfile.server -t gameserver:$IMAGE_TAG .

Next, login to Metaplay cloud with your developer portal account:

metaplay-auth login

Then, push the local game server image to the remote docker repository:

metaplay-auth push-docker-image metaplay-idler-develop gameserver:$IMAGE_TAG

Deploy the Game Server

After building and pushing the game server container image, you'll be ready to deploy the server. This is done in the same way as the standalone infrastructure stacks, but you can use the metaplay-auth tool to obtain the Kubernetes credentials and use a minimal set of Helm values to get the game server deployed.

First, let's make sure we're logged in:

metaplay-auth login

Then, deploy the image to the cloud environment with the image tag, a Helm values file to configure the environment, and Helm chart version (0.5.3 is latest at the time of writing):

metaplay-auth deploy-server \
  metaplay-idler-develop $IMAGE_TAG \
  --values=Backend/Deployments/develop-server.yaml \
  --helm-chart-version=0.6.3

INFO

Note: This step uses the pre-generated Helm values file for the deployment which is located in Backend/Deployments/develop-server.yaml. If your project does not contain this file, take a look at Release 27 Migration Guide for Managed Environments for instructions on how to add these configuration files into your project.

To configure your game client to connect to the environment, go to the developer portal and navigate to the correct project, then the correct environment, and then the 'Configure Client' tab.

To access the deployed server's LiveOps Dashboard, go to the developer portal and navigate to the correct project, then the correct environment, and you'll see the link to the 'LiveOps Dashboard'.

Tips and Tricks

The metaplay-auth command line tool is a fairly powerful tool, which you can chain together with other tools to provide identity and authentication services. This section contains some examples of how to do this.

Get Environment Details

You can get more information about the target environment:

metaplay-auth get-environment metaplay-idler-develop

The output will be a JSON object that contains details about the infrastructure and environment where the game server can be provisioned.

Get Kubernetes Credentials

To access the Kubernetes directly, you can generate a kubeconfig with:

export KUBECONFIG=/path/to/my-kubeconfig
metaplay-auth get-kubeconfig metaplay-idler-develop --output $KUBECONFIG

Then, you can access the target environment Kubernetes resources directly:

# List the server pods
kubectl get pods -l app=metaplay-server

# Get logs for a pod (-f to follow)
kubectl logs <pod-name> -f

# List Helm deployments, i.e., the gameserver and possibly load tests
helm ls

metaplay-auth and aws

As a game server administrator, you may sometimes need to access various underlying AWS resources that the game server relies on. These can include things like the S3 object storage bucket to manage files that the game server might be interacting with, the Cloudfront content delivery network distribution when you want to invalidate certain cached objects, and so on.

Get AWS credentials to access the resources directly:

metaplay-auth get-aws-credentials metaplay-idler-develop

The aws tool allows you to define profiles. The configuration structure of profiles is flexible and allows you to obtain the credentials from another external process, which can in this case be metaplay-auth, which produces ephemeral AWS credentials in a format that aws accepts.

In the aws config file (typically under ~/.aws/config), we could define a profile for the game server idler-develop following the prior example:

~/.aws/config

[profile idler-develop-admin]
credential_process = metaplay-auth get-aws-credentials metaplay-idler-develop --format json

After this, we can ensure that we are logged in metaplay-auth login and just use the regular methods for setting a profile for the aws tool (e.g. --profile switches or AWS_PROFILE environment variable):

$ metaplay-auth login
$ aws sts get-caller-identity --profile idler-develop-admin
{
    "UserId": "AXXXXXXXXXXXXXXXXXXXX:stackapi",
    "Account": "000000000000",
    "Arn": "arn:aws:sts::000000000000:assumed-role/metaplay-p1-idler-develop-gameserver-admin/stackapi"
}