The database

  1. Create an account at MongoHQ and make a database. The free one will be enough to get started.

  2. In the "Admin" tab of your database create a new user.

The server

  1. Create an account at Heroku. They have a great quickstart guide here.
  2. Create an application on your computer for Heroku and download the api server source from Github.
  3. In your MongoHQ dashboard copy the "URI" from the "Admin" tab and put your user credentials in it, and then in your Heroku application:

    heroku config:set playtomic=mongodb://the_uri_you_copied
  4. Upload the application to Heroku via the command line:

    git add .
    git commit -m "Uploading server"
    git push heroku master
  5. Find your application URL via the command line:

    heroku apps:info

Creating game credentials

You can add game credentials from the MongoHQ dashboard in the 'games' collection. The collection will be created for you automatically the first time you upload to Heroku.

	publickey: "mypublickey", 
	privatekey: "myprivatekey", 
	leaderboards: true, 
	playerlevels: true, 
	gamevars: true, 
	geoip: true

To limit access to the API server you can set the above properties to false.


If you want to use the in-game newsletter subscriptions you'll have to do a few things to set up. We're using MailChimp in our API server so:

  1. Create your account, it's free for up to 2,000 subscribers and 12,000 emails per month after which you can either pay monthly or only when you want to send newsletters
  2. Create a List and take note of the List ID, you can access it in the list's settings
  3. Define any custom fields, called MERGE TAGS, that you want to collect such as the api, the game version, the date the player first played in the "List fields and |MERGE| tags" section
  4. Create an API key in your account settings

Once you've done all of that you need to configure the server with your data:

heroku config:set mailchimp=your_api_key mailchimp_listid=your_list_id

You can also disable the default double opt-in requirement that emails players a confirmation before subscribing them by:

heroku config:set mailchimp_doubleoptin=false

By default if a player subscribes 2x their information will update but if you would like to prevent that:

heroku config:set mailchimp_allowupdates=false


This toolkit is designed to scale 'horizontally' by using eventual consistency, that means the more resources you assign it on Heroku the more capacity you can handle. Each 'dyno' or thread or equivalent for your hosting maintains its own caching and state that is periodically synced against your database or expired.

Heroku can be automatically scaled using to create and terminate 'dynos' as your load requires.

Your MongoHQ database can be manually upgraded at any time through their website.

Recommended deployment

If you're not a starving indie the ideal deployment would be:

  • 2+ dynos at Heroku because inactive single-dyno applications hibernate
  • Use your own domain in case you ever move hosting
  • SSL to keep your player's activities private
  • 'Small' database plan (or larger) at MongoHQ with Amazon S3 backups
  • HireFire configured to add a few more dynos when necessary
  • Pingdom for uptime monitoring