Development Guide

Open Match is a collection of Go gRPC services that run within Kubernetes.

Install Prerequisites

To build Open Match you'll need the following applications installed.

Git
Go
Make (Mac: install XCode)
Docker including the post-install steps.

Optional Software

Visual Studio Code for IDE. Vim and Emacs work to.
VirtualBox recommended for Minikube.

On Debian-based Linux you can install all the required packages (except Go) by running:

sudo apt-get update
sudo apt-get install -y -q make google-cloud-sdk git unzip tar

It's recommended that you install Go using their instructions because package managers tend to lag behind the latest Go releases.

Get the Code

# Create a directory for the project.
mkdir -p $HOME/workspace
cd $HOME/workspace
# Download the source code.
git clone https://github.com/googleforgames/open-match.git
cd open-match
# Print the help for the Makefile commands.
make

Typically for contributing you'll want to create a fork and use that but for purpose of this guide we'll be using the upstream/main.

Building code and images

# Reset workspace
make clean
# Run tests
make test
# Build all the images.
make build-images -j$(nproc)
# Push images to gcr.io (requires Google Cloud SDK installed)
make push-images -j$(nproc)
# Push images to Docker Hub
make REGISTRY=mydockerusername push-images -j$(nproc)
# Generate Kubernetes installation YAML files (Note that the trailing '/' is needed here)
make install/yaml/

-j$(nproc) is a flag to tell make to parallelize the commands based on the number of CPUs on your machine.

Deploying to Kubernetes

Kubernetes comes in many flavors and Open Match can be used in any of them.

We support GKE (setup guide), Minikube, and Kubernetes in Docker (KinD) in the Makefile. As long as kubectl is configured to talk to your Kubernetes cluster as the default context the Makefile will honor that.

# Step 1: Create a Kubernetes (k8s) cluster
# KinD cluster: make create-kind-cluster/delete-kind-cluster
# GKE cluster: make create-gke-cluster/delete-gke-cluster
# or create a local Minikube cluster
make create-gke-cluster
# Step 2: Build and Push Open Match Images to gcr.io
make push-images -j$(nproc)
# Step 3: Install Open Match in the cluster.
make install-chart

# Create a proxy to Open Match pods so that you can access them locally.
# This command consumes a terminal window that you can kill via Ctrl+C.
# You can run `curl -X POST http://localhost:51504/v1/frontend/tickets` to send
# a DeleteTicket request to the frontend service in the cluster.
# Then try visiting http://localhost:3000/ and view the graphs.
make proxy

# Teardown the install
make delete-chart

Iterating

While iterating on the project, you may need to:

Install/Run everything
Make some code changes
Make sure the changes compile by running make test
Build and push Docker images to your personal registry by running make push-images -j$(nproc)
Deploy the code change by running make install-chart
Verify it's working by looking at the logs or looking at the monitoring dashboard by running make proxy-grafana
Tear down Open Match by running make delete-chart

Accessing logs

To look at Open Match core services' logs, run:

# Replace open-match-frontend with the service name that you would like to access
kubectl logs -n open-match svc/open-match-frontend

API References

While integrating with Open Match you may want to understand its API surface concepts or interact with it and get a feel for how it works.

The APIs are defined in proto format under the api/ folder, with references available at open-match.dev.

You can also run make proxy-ui to exposes the Swagger UI for Open Match locally on your computer after deploying it to Kubernetes, then go to http://localhost:51500 and view the REST APIs as well as interactively call Open Match.

By default you will be talking to the frontend server but you can change the target API url to any of the following:

api/frontend.swagger.json
api/backend.swagger.json
api/synchronizer.swagger.json
api/query.swagger.json

For a more current list refer to the api/ directory of this repository. Also matchfunction.swagger.json is not supported.

IDE Support

Open Match is a standard Go project so any IDE that understands that should work. We use Go Modules which is a relatively new feature in Go so make sure the IDE you are using was built around Summer 2019. The latest version of Visual Studio Code supports it.

If your IDE is too old you can create a Go workspace.

# Create the Go workspace in $HOME/workspace/ directory.
mkdir -p $HOME/workspace/src/open-match.dev/
cd $HOME/workspace/src/open-match.dev/
# Download the source code.
git clone https://github.com/googleforgames/open-match.git
cd open-match
export GOPATH=$HOME/workspace/

Pull Requests

If you want to submit a Pull Request, make presubmit can catch most of the issues your change can run into.

Our continuous integration runs against all PRs. In order to see your build results you'll need to become a member of open-match-discuss@googlegroups.com.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!