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!
• A CI system - To set up a CI/CD pipeline, you need a continuous integration system like GitHub Actions or Bitbucket Pipelines. We recommend GitHub Actions.

Overview

The easiest way to deploy your game server to the Metaplay Cloud is to set up a CI/CD pipeline. This way, you can automate the build and deployment process as well as avoid installing tools on your local machine. We have developed pre-filled templates and other tooling to make this process as simple as possible.

In short, you will need to:

1. Create a machine user in your organization in the Metaplay Portal and give that user admin access to your environment.
2. Copy the machine user credentials and store them in your CI system as a secret.
3. Copy a pre-filled template from the Metaplay Portal into your repository.

If you wish to use a custom CI system or want to do manual deployments, you can follow the more advanced steps in the Deploy a Game Server guide.

Create a Machine User in the Portal

First, you need to create a machine user that your CI pipeline can use to access the Metaplay Cloud.

1. Navigate to the Members tab of your organization in the Metaplay Portal. Then, press Add Machine User.

   

2. Give the machine user a name of your choice, assign it the 'organization viewer' role, and check the project boxes for which you want to use this machine account.

   

3. Copy the credentials into a safe place. We don't keep them, so you'll need to create another machine user if you lose them.

   

4. Navigate to the environment(s) to which you want to deploy and grant the machine user the game-admin role. This role gives the machine user full access to the environment.

   

Setup Your CI System

Follow the instructions for the CI system that you are using. There are dedicated instructions for GitHub Actions and Bitbucket Pipelines. For other systems, follow the Deploy with Other CI Systems steps.

Deploy with GitHub Actions

For GitHub Actions, we provide pre-filled templates in the Metaplay Portal that you can adapt to your project. The templates are built with reusable workflows provided by Metaplay to keep your actions as simple as possible.

1. Create a secret in Github Actions called METAPLAY_CREDENTIALS. Store the machine user credentials created in the prior steps in this secret. If you need to get more familiar with the secrets, check out Github's own guide for more instructions.

2. Navigate to the environment in question in the Metaplay Portal. Under the 'Deploy Server' tab, you will find a pre-filled template for GitHub Actions to add to your repository.

   

3. Customize the template for your needs by giving it a name of your choice and choosing when the CI job should trigger. Then, commit and push the workflow file into your repository. You should now see it under the 'Actions' tab of your GitHub repository.

Deploy with Bitbucket Pipelines

For Bitbucket Pipelines, we provide pre-filled templates in the Metaplay Portal that you can adapt to your project.

1. Create a secret in Bitbucket Pipelines called METAPLAY_CREDENTIALS. Store the machine user credentials created in the prior steps in this secret. If you need to get more familiar with the secrets, check out Bitbucket's own guide for more instructions.

2. Navigate to the environment in question in the Metaplay Portal. Under the 'Deploy Server' tab, you will find a pre-filled template for Bitbucket Pipelines to add to your repository.

   

3. Customize the template for your needs by giving it a name of your choice and choosing when the CI job should trigger. Then, commit and push the workflow file into your repository. You should now see it under the 'Pipelines' tab of your Bitbucket repository.

Resource Starvation

Make sure you use a build machine with size: 2x at a minimum. We recommend size: 4x or larger for better performance. The default-sized runner does not have enough memory to reliably run the docker builds, which can cause the pipeline to hang indefinitely.

Deploy with Other CI Systems

For other CI systems, we provide a pre-filled shell script to use as a basis to set up your CI job.

1. First, create a secret in your CI system named METAPLAY_CREDENTIALS. Store the machine user credentials created in the previous steps as the secret's value

2. Navigate to the chosen environment in the Metaplay Portal. Under the 'Deploy Server' tab, you will find a pre-filled shell script that you can use as a basis for setting up your CI job.

   

3. Create your own CI job configuration by adapting the pre-filled shell script from the previous step. You need to modify the script to:

   1. Pass in the METAPLAY_CREDENTIALS secret with the secret handling mechanism of your CI system
   2. Configure the IMAGE_TAG to be initialized to a git commit hash or a build number, or some other unique value for each build.

Test the Workflow

Push a new commit to your repository to trigger the CI job. You should see the job run and deploy your game server to the Metaplay Cloud. You now also have easy access to the build logs in the CI system of your choice, if applicable.

Troubleshooting

A game server can end up in an unhealthy state due to various reasons. For troubleshooting, please visit the Troubleshooting page for more details.