Hands-on experiment building microservices and cloud native applications

Working with Game On! Locally

Developing and testing your room locally in a production-like environment is an important aspect of Twelve factor applications, as it reduces the likelihood that what you create locally will fail in new and unexpected ways when activated in production.

Game On! is a containerized application that uses replaceable backing services that can also run locally in containers (sometimes with minor substitutions, as we’ll see). We like this for two reasons: 1) we can directly see what happens when we prod things with a stick, and 2) we can be much more destructive with local copies without worrying about messing something up.

Using Vagrant

The Vagrantfile defined in the gameontext/gameon (root) project will ensure that you’re using the right versions of everything, regardless of which orchestration engine you use, at the cost of getting one version right.

You need at least version 1.9.8 of Vagrant, which you can install using packages from the Vagrant downloads page.

Once you have Vagrant installed:

  1. Use vagrant up to provision and launch the Vagrant VM.
  2. Use vagrant ssh to create a command shell in the VM
    • All commands in the following sections are run in this shell
    • You will start in the /vagrant directory
      • This directory is 'shared'
      • It is the directory containing the Vagrantfile (the root gameon project)
  3. When you’re done, use vagrant down to stop the VM.
  4. Use vagrant destroy to tear down the VM completely.

Using Docker

Installation instructions for Docker vary by platform. On Windows and macOS, you can also choose between Docker native and Docker Toolbox. Both should work.

We provide pre-built images on dockerhub to simplify the steps required to run the game locally.

Container orchestration

For sanity, you need help of some kind to manage starting and stopping images. Even with the orchestrators, we still wrap invocations with shell scripts: the scripts help ensure we all issue the same commands the same way every time.

Starting game services locally (TL;DR)

  1. Obtain the source for the root project (gameontext/gameon)
  2. Change to the gameon directory

    $ cd gameon
  3. Setup your environment (one time).

    $ ./ choose       # choose Docker Compose or Kubernetes
    $ eval $(./ env)  # set aliases for admin scripts
    $ alias go-run               # confirm `` script location
  4. Set up core game services:

    $ go-run setup
  5. Start core game services:

    $ go-run up
  6. Carry on with building your room or other adventures
  7. Clean up

    $ go-run down

Modifying Core Game services

If you change your mind, and decide you want to start hacking on a core game service, no worries! You can mix and match the two approaches.

We use git submodules to allow editing of core game services while working with the gameontext/gameon (root) project to coordinate deployment.


When using git submodules, please do not commit any changes to submodule versions. Submodule versions are maintained by automated builds.

The following instructions assume you’ve cloned the root repository, and are interested in editing the map service as an example:

  1. Change to the gameon directory

    cd gameon
  2. Obtain the source for the project that you want to change.

    git submodule init map
    git submodule update map
  3. Make your changes from within the child directory

    cd map
    git checkout -b newbranch

    Then edit source or docker/image files using your favorite IDE.

  4. Compile the source and rebuild docker image
  5. Push your changes to a new branch. From the map directory:

    git add -u
    git commit -s

    Once you make your commit, if you go back to the root directory, you will see a pending change for map. This indicates that the submodule is different than the version from the current branch of the root project. Do not check in this change. Sadly, these files can not be added to .gitignore.

    Care must be taken to avoid staging these files if you otherwise end up making changes to files in the root project itself.


Supporting 3rd party auth

3rd party authentication (twitter, github, etc.) will not work locally, but the anonymous/dummy user will. If you want to test with one of the 3rd party authentication providers, you’ll need to set up your own tokens to do so.