Dependencies

• High-level understanding of Metaplay Cloud - We recommend reading the Introduction to Cloud Deployments to understand the key concepts of cloud deployments.
• An environment in Metaplay Portal - To be able to deploy a game server to the Metaplay Cloud, you need a project with an environment to deploy to. Contact us to get started!
• Having the required tools installed on your system - To follow the steps provided, you need: Docker, metaplay-auth, and optionally, jq.

Install metaplay-auth CLI

The metaplay-auth CLI tool is a powerful utility that provides various commands for interacting with cloud deployments in the Metaplay Cloud. The CLI tool helps you obtain the required credentials as well as easily fetch relevant details required for building, pushing, and deploying a game server to the Metaplay 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 CLI Tool

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

1. It allows you to log into the Metaplay Portal and obtain associated tokens for interacting with different Metaplay APIs.
2. It allows you to obtain ephemeral Kubernetes and AWS credentials which are needed for pushing images and deploying game servers into environments.

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 Portal account. 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

The next step is to create a game server image with Metaplay SDK and Docker. You need a unique tag for this build. In this walkthrough, we use current timestamps, 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 .

Then, push the local game server image into Metaplay Cloud:

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

Deploy a Game Server

With a game server image and access to an environment, you should be able to deploy the game server into the Metaplay Cloud. For the deployment, you would need:

• An image tag that matches the image that you just pushed to the Metaplay Cloud.
• A Helm values file at Backend/Deployments/develop-server.yaml to configure the deployment. For more details, please check Configuring a Deployment.
• A Helm chart version. Please check the Metaplay Compatibility Matrix for more information regarding version compatibility against Metaplay SDK releases.

metaplay-auth \
  deploy-server \ # command to deploy a server
  metaplay-idler-develop \ # specify the target Environment, must be in the format of {Organization}-{Project}-{Environment}
  $IMAGE_TAG \ # image tag for deployment
  --values=Backend/Deployments/develop-server.yaml \ # The default path for the Helm deployment file
  --helm-chart-version=0.6.3 # It's recommended to use the latest Helm chart version available

INFO

When specifying the target environment for a Deployment, you should use the format of {Organization}-{Project}-{Environment}, like metaplay-idler-develop, for example.

INFO

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 the Release 27 Migration Guide for Managed Environments for instructions on how to add these configuration files into your project.

If successfully executed, you will be able to visit a LiveOps Dashboard by following the link displayed in the Metaplay Portal. Navigate to the correct environment, and you will find 'Quick Link' on the landing page.

Connect to a Game Server

To configure your game client to connect to a deployment, go to the Metaplay Portal and navigate to the target environment; there you will find detailed information under the 'Configure Client' tab.

Tips and Tricks

The metaplay-auth CLI tool is fairly powerful, and you can chain it 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 inspect an 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 deployed.

For more advanced usages of the metaplay-auth CLI tool, you can get a list of supported commands by:

metaplay-auth --help

Direct Access to Cloud Resources

Although Metaplay Cloud is a fully managed platform that keeps you hassle-free from the underlying infrastructure and cloud-native implementation, in some cases, you may need to directly access certain cloud resources, for example, to persist secrets outside of the game server image. For such advanced use cases, please visit the Interacting with AWS page.