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.
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:
vagrant upto provision and launch the Vagrant VM.
vagrant sshto create a command shell in the VM
All commands in the following sections are run in this shell
You will start in the
This directory is 'shared'
It is the directory containing the Vagrantfile (the root
When you’re done, use
vagrant downto stop the VM.
vagrant destroyto tear down the VM completely.
For sanity, you need help of some kind to manage starting and stopping images. Even with the orchstrators, we still wrap invocations with shell scripts: the scripts help ensure we all issue the same commands the same way every time.
The following sections apply to both Docker Compose and Kubernetes.
Starting game services locally (TL;DR)
Obtain the source for this repository:
git clone https://github.com/gameontext/gameon.git
git clone firstname.lastname@example.org:gameontext/gameon.git
Change to the gameon directory
Setup your environment (one time).
Start core game services:
Carry on with building your room!
When Game On! runs in the cloud, it uses etcd to obtain its configuration.
When running locally it expects all this to be fed to it via the environment.
gameon.env file defined in the root directory provides this local
configuration, and is consumed by both Docker Compose and Kubernetes.
Some addional notes regarding environment-specific config:
When you run natively, the "host" for your containers is the OS itself, so 127.0.0.1 will work just fine (default url in
When you run in Docker Toolbox, there is a VirtualMachine acting as the host for your containers. This means that (for URLs and other things) you need to use the IP of the VM. A
gameon.<DOCKER_MACHINE_NAME>envfile will be created as a modified copy of
Similarly, if you are running with Vagrant, you need to use the Vagrant VM’s IP address. A
gameon.vagrantenvfile will be created in the root directory as a modified copy of
SSH Keys and KeyStores
Because Game On! uses a Certificate for HTTPS and for JWT signing, we need to
generate one for local use. We create a special mapped volume (called
that provides a generated local keystore to containers.
Scripts will ensure that this volume exists.
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.
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:
Change to the gameon directory
Obtain the source for the project that you want to change.
git submodule init map git submodule update map
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.Tip
If you plan to edit projects with Eclipse, run
./bin/eclipse.shto generate eclipse project files.
Compile the source and rebuild docker image
Push your changes to a new branch. From the map directory:
git add -u git commit -sNote
Git commits must be signed
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
Care must be taken to avoid staging these files if you otherwise end up making changes to files in the root project itself.
Iterative development of Java applications with WDT
If you’re using Eclipse for development, and have opted for the iterative
docker-compose.override.yml for volumes, e.g.),
we recommend using WebSphere Developer Tools (WDT) to work with the Java
services contained in the sample. There is some (one time) configuration
required to make WDT happy with the docker-hosted applications,
but you are then free to use eclipse to make changes to the project that will
be immediately picked up by the running server without having to rebuild
or restart anything.
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.
Determining the host IP address (Docker Toolbox)
After you have Docker Toolbox installed, verify the host machine name:
docker-machine ls. The default name is
default, but if you’re a former
Boot2Docker user, it may be
dev instead. Substitute this value appropriately
in what follows.
If you aren’t using the docker quick-start terminal, you’ll need to set the
docker environment variables in your command shell using
eval "$(docker-machine env default)".
Get the IP address for your host using
docker-machine ip default.
./docker/go-run.sh will create a
gameon.<DOCKER_MACHINE_NAME>env file to account for the IP address