Skip to content
Build an on-demand Minecraft server on Amazon EC2.
Branch: master
Clone or download
Brett Adam and toffer Handle upstream changes to Oracle's download site.
Use patched OAB from ladios/oab-java6 to resolve upstream changes
to Oracle's java download site.

See flexiondotorg/oab-java6#125

Fixes #16.
Latest commit 62b74cb Jan 21, 2014
Type Name Latest commit message Commit time
Failed to load latest commit information.
manifests Clean slate for publishing to Github. Mar 6, 2013
modules Handle upstream changes to Oracle's download site. Jan 21, 2014
.gitignore Added standard OS X ignore file Jul 10, 2013
LICENSE.txt More README improvements. Jul 12, 2013
cloud-config Clean slate for publishing to Github. Mar 6, 2013


Build an on-demand Minecraft server on Amazon EC2.

Minecloud-AMI installs and configures the Minecraft server and various management scripts to build a custom EC2 AMI--one that's designed to back up Minecraft world data to and restore world data from Amazon's S3 service upon server startup and shutdown.


An effective, on-demand, Minecraft server needs more than just Java and the Minecraft server installed.

Ideally, an on-demand server should do the following:

  • Restore your Minecraft world data from S3 backup upon server startup.
  • Save your Minecraft world data to S3 periodically while it is running, and upon server shutdown.
  • Update the Minecraft server when a new version becomes available.

Minecloud-AMI is designed to create a Minecraft EC2 AMI that does all of the above, using a set of Puppet manifests to build, install and configure the necessary software.

Despite using Puppet, you don't need to know anything about Puppet to create the AMI, since a script is included. It launches a stock Ubuntu cloud image on EC2, applies the Puppet manifests, and creates an AMI image for you. (No need to set up a Puppet Master server.)


Setup is a bit involved for building your first AMI, and requires familiarity with Amazon Web Services (AWS) and the Unix (or Mac) command line. The first set of steps involves setting up and configuring your AWS account. The second set is focused on creating a Python virtualenv so that you can run the script.

AWS Account

  1. Set up an Amazon AWS account for EC2 and S3.

    Make a note of your AWS security credentials: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

  2. Import a Key Pair using the AWS Web console.

    Generate a new SSH key on your local machine called MinecraftEC2.

     $ ssh-keygen -f ~/.ssh/MinecraftEC2

    Upload the public key to AWS. The script will expect the private key MinecraftEC2 to be located in your $HOME/.ssh directory.

  3. Create a Security Group using the AWS Web console.

    It should be called minecraft and should allow inbound traffic on two ports: 22 (SSH), and 25565 (Minecraft).

  4. Create an S3 bucket.

    Use the AWS Web interface to create an S3 bucket in which to back up your Minecraft world data files.

  5. Set local environment variables.

    AWS security credentials from Step #1:

     $ export AWS_ACCESS_KEY_ID=...
     $ export AWS_SECRET_ACCESS_KEY=...

    Name of S3 bucket (created in the previous step) to store Minecraft world data files.

     $ export MSM_S3_BUCKET=...


  1. Set up a virtualenv and activate it.

    • Install 'pip' command. This installs pip in the global site-packages location.

        $ sudo easy_install pip
    • Install 'virtualenv'. Again, this tool will also be globally available.

        $ sudo pip install virtualenv
    • Create a directory for the minecloud project. This is where you will create a virtualenv and clone the minecloud git repository.

        $ mkdir ~/minecloud-project
    • Change directory.

        $ cd ~/minecloud-project
    • Create a virtualenv called 'venv'.

        $ virtualenv venv
    • Activate the virtualenv.

        $ source venv/bin/activate
  2. Clone repository.

     (venv)$ git clone
     (venv)$ cd minecloud-ami
  3. Install requirements.

     (venv)$ pip install -r requirements.txt


The takes a base Ubuntu 12.04 (Precise Pangolin) AMI and customizes it to create a Mincloud AMI.

By default, the script will create the custom AMI in the us-west-2 region (Oregon). If you want to create an AMI for use in a different EC2 region, edit the env.ec2_region near the top of the script. A list of regions and their associated codes can be found here.

If you select a region different than the default us-west-2 region, you will also need to change the env.ec2_amis variable, since AMI Ids are specific to regions. To find the official Ubuntu 12.04 AMI for your region in the AWS console, use the search string 099720109477 ubuntu-precise-12.04-amd64-server on the public AMIs list. Alternatively, use Canonical's Amazon EC2 AMI Locator.

Note: Be sure to import the key pair and create the security group in the same region specified in the script.

  • Build the AMI.

      (venv)$ ./

The script takes about 20 minutes to complete. When it finishes, it will output the AMI ID.


Many projects and companies have been instrumental in making this one possible. In addition to the more obvious choices (Thanks, Amazon! Thanks, Puppet Labs! Thanks, Mojang!), several other projects deserve special mention:


MIT License. Copyright (c) 2013 Tom Offermann.

You can’t perform that action at this time.