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.

Creating 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

You can navigate to the Deploy Server tab of the environment in the Metaplay Portal to find pre-filled templates for various CI systems. We recommend using GitHub Actions and will provide instructions for that system here.

Our templates leverage our reusable workflows and CLI tooling to keep them as simple as possible.

Save the Machine User Credentials

Create a secret in GitHub Actions called METAPLAY_CREDENTIALS and give it the machine user credentials created earlier on this page. You can find the secrets tab in the settings of your repository.

Add the Workflow to Your Repository

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.

Example template:

# Rename this action to what you want, this is what shows in the left sidebar in Github Actions
name: Build game server and deploy to develop environment

# Configure when this Github Action is triggered
on:
  # Enable manual triggering
  workflow_dispatch:

  # Trigger on all commits to branch 'main'
  # TODO: Replace this with your own desired trigger (see https://docs.github.com/en/actions/using-workflows/triggering-a-workflow)
  push:
    branches: main

jobs:
  # Build the server and deploy into the cloud
  build-and-deploy-server:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Setup Metaplay CLI
        uses: metaplay-shared/github-workflows/setup-auth-cli@v0
        with:
          credentials: ${{ secrets.METAPLAY_CREDENTIALS }}

      # TODO: Update --project-root path if your Backend/ directory is not located in the repository root
      - name: Build server image
        run: metaplay-auth build-image -t gameserver:$GITHUB_SHA --project-root=.

      - name: Push server image to environment registry
        run: metaplay-auth push-docker-image idler-develop gameserver:$GITHUB_SHA

      - name: Deploy server to target environment
        run: metaplay-auth deploy-server idler-develop $GITHUB_SHA --values="Backend/Deployments/develop-server.yaml" --helm-chart-version="0.6.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 in the .github/workflows directory.

You should now see it under the Actions tab of your GitHub repository.

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 GitHub Actions UI.

Check Your CI Runner Size

If you are using Bitbucket Pipelines, make sure you use a build machine with size: 2x at a minimum. The default-sized runner does not have enough memory to reliably run the Docker builds, and this can cause the pipeline to hang indefinitely.

Other systems may also benefit from using beefier runners.

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.