Game On! is both a sample microservices application, and a throwback text adventure brought to you by the WASdev team at IBM. This application demonstrates how microservice architectures work from two points of view:
- As a Player: navigate through a network/maze of rooms. Each room is an autonomous service, supports chat, and may provide interaction with items (some of which may be in the room, some of which might be separately defined services as well).
- As a Developer: learn about microservice architectures and their supporting infrastructure by creating your own microservices to extend the game.
You can learn more about Game On! at http://game-on.org/.
This walkthrough will guide you through creating and deploying a microservice that adds a simple room to the running Game On! microservices application. You will be shown how to setup a room that is implemented in the Java programming language using Websphere Liberty and (a) deployed as a Cloud Foundry application in Bluemix, or (b) as a docker container that can be run locally or published to the IBM Container Service in Bluemix.
- Maven
- Java 8: Any compliant JVM should work.
- Java 8 JDK from Oracle
- Java 8 JDK from IBM (AIX, Linux, z/OS, IBM i),
or Download a Liberty server package that contains the IBM JDK (Windows, Linux)
The source code is located in GitHub, navigate to our repository and create a fork of the repository into your own repo. Navigate to your new fork and clone the repository with git clone https://github.com/<<yourGitHubId>>/gameon-room-java.git
. Alternatively you can download the ZIP file and unzip the code on to your local machine.
cd gameon-room-java
mvn install
mvn package -PstartLocal
After running this, you will have the server running locally at http://localhost:9080/. You can use a browser extension to play with the WebSocket according to the Game On! WebSocket protocol.
To deploy your room you can either:
Microservices in production should support automatic scaling, with multiple instances of the room microservice running in parallel, with new instances starting or existing instances stopping at unpredictable times.
To register your room you need the websocket endpoint. This will vary depending on where you have deployed your app, but should look something like:
- Bluemix/Container group in IBM Container Service:
- US South:
ws://<cf-app-name>.mybluemix.net/room
- United Kingdom:
ws://<cf-app-name>.eu-gb.mybluemix.net/room
- US South:
- Single container instance in IBM Container Service
ws://<ip address>:9080/room
Use the Edit Rooms dialog in Game On! to register your room:
- Go to GameOn and sign in.
- Once you are signed in, go to the top right of the browser window and click on your username (or person icon).
- From this window, again click the top right panel to select Edit rooms.
- Under Select or create a room, make sure create a room is selected from the dropdown.
- Fill in the room information as specified. If you don't know all the details yet, leave those blank and come back and fill them in later.
- Click Create and the room will be created for you.
Once the room is set up and it has registered with Game On!, it will be accessible as a room in the game.
- If you aren't in The First Room, use
/sos
to return there. - Use the Game On! command
/listmyrooms
from The First Room, to see your list of rooms. Your newly registered room should appear in that list. - Use the
/teleport
command to go directly to your room from The First Room to see it in action.
Congratulations, you've deployed a microservice that extended an existing microservices-based application so that it can do something new.
Suggested activities:
- Make it more resilient -- add additional instances using the autoscaling add-on: https://console.ng.bluemix.net/catalog/services/auto-scaling
- Consider how to allow chat messages to propagate between independent instances using a shared datastore or cache, or an event bus, or...
- Want some more ideas, check out the Advanced Adventures section of our GitBook.
The Game On! host provides a set a universal commands:
- /exits - List of all exits from the current room.
- /help - List of all available commands for the current room.
- /sos - Go back to The First Room.
The First Room is usually where new users will start in Game On!. From there, additional commands are available and maintained by Game On!. For the list of current commands use the /help
command.
Sign up for Bluemix at https://console.ng.bluemix.net and DevOps Services at https://hub.jazz.net. When you sign up, you'll create an IBM ID, create an alias, and register with Bluemix.
- Make a note of your username and org, as you will need both later.
- By default, the space is dev and the org is the project creator's user name. For example, if sara@example.com signs in to Bluemix for the first time, the active space is dev and the org is sara@example.com.
- Make a note of your region! (US South, United Kingdom, or Australia)
- When you log into Bluemix, your logged in username, organization, and space are shown in the top right. If you click in the top right corner, you'll see the region displayed in the panel displayed on the right side of the screen.
- Login to the Cloud Foundry command line:
cf login
- Enter Bluemix API endpoint
- From the Bluemix console, click on your username in the top right corner. You'll see the region displayed in the panel on the right side of the screen.
- US South:
https://api.ng.bluemix.net
- London:
https://api.eu-gb.bluemix.net
- Enter email and password for Bluemix login
- Enter the Bluemix organization
- Enter the Bluemix space
cf push <cf-app-name> -p gojava-wlpcfg/target/wlp/usr/servers/gojava-room/gojava-room.zip
NOTE: Choose a unique app name to be included as part of the URL (cf-app-name
). It must not contain spaces or special characters.
After your room has been pushed, you should be able to view it at:
- US South:
http://<cf-app-name>.mybluemix.net/
- United Kingdom:
http://<cf-app-name>.eu-gb.mybluemix.net/
app.name
is a unique, URL-friendly name for your deployed Bluemix app.gameon.id
andgameon.secret
are those retrieved earlier.
Now you need to register your room using the Websocket URL. Go to your app endpoint, either by going directly to the URL or by clicking on the route in your Bluemix Dashboard to see your Websocket URL. This will vary by region, but should look something like:
- US South:
ws://<cf-app-name>.mybluemix.net/room
- United Kingdom:
ws://<cf-app-name>.eu-gb.mybluemix.net/room
It is possible to deploy your room locally into a Docker container. This can be useful if you want to test aspects such as the room registration and configuration retrieval. Remember, this room will be running locally on your hardware so Game On will not be able to access it, unless your machine is also publicly accessible.
Once docker is installed, then you deploy your room with
mvn package
to build your room.- Create a file called
docker-compose.override.yml
which contains the folllowing
gojava:
volumes:
- './gojava-wlpcfg/target/wlp/usr/servers/gojava-room:/opt/ibm/wlp/usr/servers/defaultServer'
docker-compose build
docker-compose up
Note: you can optionally use docker-compose up -d
to run the container as a background process. Use docker-compose stop
to stop the container.
After this you will have a docker container with your room, running Liberty, and listening on port 9080.
- If you’re running a *nix variant, you can access it at http://127.0.0.1:9080
- If you’re running Mac or Windows, access it using the IP of the host
A note about docker-compose.override.yml
, this is an override file that can be used to change, or add to, an existing docker build file. In this case, it maps the file system on the local machine into the dropins directory for the Liberty server running inside the container. The end result is that if you make some changes to your code and run mvn package
again to rebuild your war file, then Liberty will see that the file has changed and automatically reload your room without having to build or restart the container.
It is possible to attach a debugger to your room so that you can set breakpoints and step through code. Add the following lines to the docker-compose.override.yml
file
ports:
- "7777:7777"
environment:
- LIBERTY_MODE: debug
The ports
section instructs docker to expose the port 7777 from inside the container, so that the debugger can attach. The environment
statement sets an environment variable called LIBERTY_MODE
to debug. This variable is read by the Liberty startup script and controls how the server is started, in this case in debug mode.
- Log in to the IBM container service. This needs to be done in two stages:
- Log into the Cloud Foundry CLI using
cf login
. Ypu will need to specify the API endpoint asapi.ng.bluemix.net
for the US South server, orapi.eu-gb.bluemix.net
for the UK server. - After this run the command
cf ic login
. This will perform the authentication to the IBM Container Service. - Build the container in the Bluemix registry by running the command
cf ic build -t gojava .
from inside thegojava-wlpcfg
directory. - Run
cf ic images
and check your image is available. - Start the container by running the command
cf ic run -p 9080 --name gojava <registry>/<namespace>/gojava
. You can find the full path from the output ofcf ic images
. An example would be:
cf ic run -p 9080 --name gojava registry.ng.bluemix.net/pavittr/gojava
- While you are waiting for the container to start, request a public IP address using the command
cf ic ip request
. This will return you a public IP address you can bind to your container. - With the returned IP address, bind it using the command
cf ic ip bind <ip address> gojava
. - Issue
cf ic ps
, and wait for your container to go from "Networking" to "Running". - Now you can go to
http://<ip address>:9080
and access the Liberty welcome page.
Instead of deploying a container as a single instance, you can instead deploy a container group. A container group can be used to deploy multiple instances of the same container and load balance between them.
- Log in to the IBM container service. This needs to be done in two stages:
- Log into the Cloud Foundry CLI using
cf login
. You will need to specify the API endpoint asapi.ng.bluemix.net
for the US South server, orapi.eu-gb.bluemix.net
for the UK server. - After this run the command
cf ic login
. This will perform the authentication to the IBM Container Service. - Run
cf ic images
and check thegojava
image is available. If not, run the commandcf ic build -t gojava .
from inside thegojava-wlpcfg
directory to create it. - Create the container group by running
cf ic group create -p 9080 -n <appName> --name gojavagroup <registry>/<namespace>/gojava
. You can find the full path from the output ofcf ic images
. An example would be:
cf ic group create -p 9080 --name gojavagroup registry.ng.bluemix.net/pavittr/gojava
- Run the command
cf ic route map -n <appHost> -d mybluemix.net gojavagroup
. This will make your containers available at .mybluemix.net. - Run the command
cf ic group instances gojavagroup
to check the status of your instances. Once they are in "Running" state your group is ready to use. - Now you can go to
http://<appHost>.mybluemix.net
and access the Liberty welcome page.