Forge Home


Minecraft / CraftBukkit Server v2


10,364 latest version

1.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.1.6 (latest)
  • 2.1.5
  • 2.1.4
  • 2.1.1
released Mar 16th 2014

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'andschwa-minecraft', '2.1.6'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add andschwa-minecraft
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install andschwa-minecraft --version 2.1.6

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



andschwa/minecraft — version 2.1.6 Mar 16th 2014

Puppet Module for Minecraft v2

puppet-minecraft installs and configures your Minecraft or CraftBukkit server with Puppet!

This is a derivative work of Branan Purvine-Riley's Minecraft module, with improvements including: version selection, CraftBukkit support, a plugin resource, and settings managed via templates. It is released under the original Apache License, Version 2.0.

This module has been tested on Ubuntu Server 12.04.4 with Puppet 3.4.3.


The simplest possible usage is:

include minecraft

This entire class is parameterized (see the minecraft class for details), and can be configured through hiera.

Parameters are available which control how the Minecraft installation behaves:

  • user: The user account for the Minecraft service
  • group: The user group for the Minecraft service
  • install_dir: The directory in which Minecraft stores its data
  • source: Minecraft (semvar) or CraftBukkit ('recommended', 'beta', or 'dev'), or direct source (URL for wget)
  • autostart: Start the service at boot
  • manage_java: Manage the JRE package
  • heap_size: The maximum Java heap size for the Minecraft service in megabytes
  • heap_start: The initial Java heap size for the Minecraft service in megabytes

Minecraft Versions / CraftBukkit Builds

A particular version of Minecraft server can be downloaded by specifying the source parameter. This parameter accepts a semantic version (representing a vanilla Minecraft server), a snapshot version, or for a CraftBukkit installation, one of 'recommended', 'beta', or 'dev'. Latest vanilla version as of this writing is 1.7.5.

Please note that once a JAR file (the server) has been downloaded to install_dir, if you want to switch, you will need to manually remove it so that the wget::fetch resource can update; this is a good thing as it means the tags (e.g. "recommended") will not auto-update your server. This is good because you must beware incompatibilities among Minecraft and CraftBukkit versions with world files, settings, etc, so backup and test thoroughly before you update. (At least rolling back to an old version is easy.)

Speaking of old versions, prior to the release of Minecraft 1.6, the downloads were hosted at a different location, but since these are quite old, this module does not currently support it. Submit a Pull Request if you add support, or make an issue if you want me to do so.

Server configuration

Full configuration of the Minecraft server is supported. Simply specify the parameter with the server setting when declaring the class:

class { 'minecraft':
  source     => 'dev',
  heap_size  => 2048,
  difficulty => 2,
  motd       => 'Managed by Puppet!',
  ops        => [ 'op1', 'op2' ]

Hiera configuration can also be done. In YAML:

minecraft::source: 'dev'
minecraft::heap_size: 2048
minecraft::difficulty: 2
minecraft::motd: 'Managed by Puppet, with Hiera!'
  - 'op1'
  - 'op2'

Note that the server property name will use an underscore instead of a dash, and may not exactly match the name. Also, refrain from using 'undef' for the server properties, as Puppet will place 'undef' as a string in the template; instead, use the emptry string: ''. (It's either this or add a bunch of template logic to check for an undef value first, for every parameter, do it and Pull Request if you'd like.)

Managing players

This module manages the Minecraft player settings through templates. To add players to a particular list, declare an array of them:

class { 'minecraft':
  ops                => 'me',
  banned_players     => [ 'griefer', 'badboy' ],
  banned_ips         => '',         # Don't actually do this
  white_list_players => [ 'my_best_friend' ] # Minecraft auto-includes ops

Note that when any of these parameters is set to undef, Puppet will not manage the corresponding file, allowing you to manage it via commands in Minecraft. However, if specified, Puppet will manage the file, and overwrite any manual changes on the next application of Puppet. (There is also the "replace" attribute on the Puppet file resource, but this is not what we want because, if the file is being managed, we want changes in the manifest to be updated in the files.)

To enable the whitelist, you must both set it to true in the class, and add players to the whitelist here, as they affect separate templates. Additionally, blacklists (banned IPs/players) is pointless if the whitelist is enabled, and is only shown here concurrently for demonstration purposes.


If manage_java is true, this module will use Puppetlabs' Java module to install the necessary Java Runtime Environment.

Adding CraftBukkit Plugins

CraftBukkit plugins can be installed by using the defined resource minecraft::plugin. You must specify the plugin name (lacking the '.jar' file extension) and the complete URL for the download source.

Dynmap Example

The Dynmap plugin can be configured like this:

minecraft::plugin { 'dynmap':
  source => ''

Or using Hiera like this:


Once enabled, a web-based map of the server will be available at localhost:8123. James Fryman's nginx module could then be used to proxy the server through map.domain.tld like thus:

nginx::resource::vhost { 'map.domain.tld':
  proxy            => 'http://localhost:8123',
  proxy_set_header => [ 'Host $host' ],

Or again in Hiera,

    proxy: http://localhost:8123
      - Host $host

Note that Nginx setup is not within the scope of this module, and is simply provided as a tip.


This package uses Puppetlabs' stdlib module for the ensure_resource function, which it uses on the screen package (utilized for running the Minecraft server as a background service). This is currently the safest way to declare a possibly-conflicting dependency.


Testing of this package occurs on an Ubuntu 12.04.4 LTS machine, using Puppet 3.4.3. This is made easy using vagrant, and my own box


My contributions as indicated by the git repository's history are Copyright 2014 Andrew Schwartzmeyer, and as stated above, are released under the included license.