Installing COAL



Golden Carrot (v1.1)

  1. Dynamic world status updates.
  2. Better handling of crashed Minecraft server processes.
  3. Collapse ‘Chats’ and ‘Players’ pages to the world home page.

Tagged on January 4, 2015

Steak (v1)

  1. Initial release.

Tagged on October 20, 2014


  1. Create a Google Cloud Project for your new COAL installation. Take note of the Project ID you select (e.g. [my-project-id]).
  2. Optionally, in Settings, enable billing. COAL should be able to run comfortably under the daily free App Engine quota for most relatively small, lightly-populated worlds.
  3. Fork, clone, or download the MC COAL code repository. Make sure any new fork or clone is a private repository as it will contain sensitive information (like the main_SECRET_KEY).


The master/trunk of the MC COAL code repository will always contain the latest tagged, stable release. Ongoing (potentially unstable) development will be done on branches.

  1. Change the application name (i.e. my-mc-coal) in the first line of your repository’s app.yaml to the Project ID you created above.
  2. Update your installation settings in your repository’s file:
  1. Change the main_SECRET_KEY value to a unique random string. You can use this link to generate a unique string value.
  2. Change the main_TITLE and main_DESCRIPTION to strings that are appropriate for your COAL installation.
  3. You do not have to change oauth_SECRET_KEY or oauth_TOKEN_EXPIRES_IN. The defaults will work just fine.
  1. Complete the sub-steps below if you intend to host worlds on Google Compute Engine:
  1. In Settings enable billing if you haven’t already. There is no daily free Google Compute Engine quota.
  2. In APIs, make sure that Google Compute Engine, Google Cloud Storage and Google Cloud Storage JSON API are ON.
  3. In Permissions make note of the Google Compute Engine service account email address. This should be of the form [project number] or [project number] Also, make sure there is an entry for [my-project-id] If it isn’t there, add it as a owner member.
  4. Add the Google Compute Engine service account email address to the acl section of queue.yaml. When finished, the file should look something like this
- name: default
  rate: 5/s

- name: controller
  mode: pull
  - user_email:
  1. Deploy your modified code in either of two ways:
  • Use the Push-to-Deploy Release Pipeline to deploy automatically from your github repository.

    1. Finish the steps under Setting up a Release Pipeline


    You do not have to complete Step 1 (install Git on your local system) if you intend to deploy only from a Github-hosted fork of the MC COAL code repository.

    1. Click the “Connect to a repository hosted on Github” button.
    2. After authenticating with github, choose the clone or fork of the repository you created in step 3 above.
    3. Choose the “Deploy Source Only” option.
    4. Optionally enter your email address to receive status updates for your deployments.
    5. Make a change to any file in your repository (for instance, add a blank line or comment to and save/push the change. This should initiate a deploy. If you entered your email address when setting up the Release Pipeline you should get an email when the deploy completes.
  • If you are familiar with Google Cloud Platform python development, feel free to use the App Engine python developer tools

  1. After the deployment has completed, browse to your COAL administrator page at https://[my-project-id]


It may take a few minutes after an initial successful deployment for database indexes to build. If you get a 500 error response when browing your COAL site right after deployment, you might have to wait a few minutes for the indexes to finish building.


For bootstrapping purposes, the first user to request this page is made an administrator, so make sure to do this as soon as possible.

World Hosting

There are two options for hosting your minecraft world(s): let your COAL host your world on Google Compute Engine (easy!) or host your world elsewhere (more work for you!). You can mix both kinds of hosted worlds on a single COAL install.

Hosting Worlds On Google Compute Engine

  1. Define a new minecraft version in Admin/Define New Minecraft Version/URL. Enter a version name (i.e. 1.7.10) and the URL where the Minecraft Server JAR for that version can be downloaded (i.e.


A list of all available versions and server JAR download links is available at COAL has been tested with versions as far back as 1.4.7.

  1. Create a new server in Admin/Create GCE-Hosted World. Then hit the play button to start the server. This can take a few minutes if a GCE instance has to be started up for the first time.
  2. When the world status is “Playing” the IP address of the server will be shown. Use this IP address to connect your minecraft client to the new world.
  3. Play! No additional infrastructure set up needed.
  4. Additional administrator settings are available in Admin/Configure. Here you can modify settings such as the type of machine instance to use (which determines the speed of the CPU and amount of memory available), the size of the disk (larger disks are faster), the number of saved game versions to keep in the cloud, and whether to use a static IP address.


Changes made on the Admin Configuration page won’t be live until a new GCE instance is started. To shut down the currently running instance, click the “Kill Instance” button on the Admin page. To start a new instance, hit “Play” for one of your worlds.


Make sure all worlds are paused before killing the instance. Failure to do so may result in corrupted world files. Note that large worlds can take a few minutes to shutdown and save.

Hosting Worlds On Other Servers

If you already have a Minecraft multi-player world running on a UNIX-based server you can connect it to your COAL.

Hosting Server Prerequisites

The following libraries are required to be installed on the server that is hosting your world.

Agent Installation

  1. Create a new directory called mc-coal in your minecraft server’s directory (the one with
  2. Download the following files from your COAL into the new mc-coal directory:
wget https://[my-project-id] -o
wget https://[my-project-id] -o
  1. Download the following files from your COAL into your minecraft server’s directory
wget https://[my-project-id] -o log4j2.xml
wget https://[my-project-id] -o
wget https://[my-project-id] -o

Run Agent

  1. Create a new COAL world by clicking the Admin/Create External-Server-Hosted World and note the Agent Client ID and Agent Secret.
  2. On your Minecraft server host, in the mc-coal directory, run with the coal_host, agent_client_id, and agent_secret for your server:
[~/minecraft-server/mc-coal] $ python --coal_host=[my-project-id] --agent_client_id=mc-coal-agent-12345 --agent_secret=ow9mLT8rev1e8og5AWeN1TyBM7EXZYiCntw8dj4d
2014-01-01 23:00:01 : main     INFO   Monitoring '../server.log' and reporting to '[my-project-id]'...
  1. Edit the java configuration parameters within the script as desired.
  2. Start the minecraft server with the script:
[~/minecraft-server] $ ./
2014-01-21 22:15:09,540 DEBUG Generated plugins in 0.000023000 seconds
2014-01-21 22:15:09,588 DEBUG Shutting down OutputStreamManager SYSTEM_OUT
2014-01-21 22:15:09,588 DEBUG Reconfiguration completed
  1. To stop the minecraft server later, use the script:
[~/minecraft_server] $ ./
Stopping MineCraft Server PID=5989
2014-01-22 22:12:19,540 DEBUG ServletContext not present - WebLookup not added
2014-01-22 22:12:19,541 DEBUG Shutting down FileManager server.log
MineCraft shutdown complete.