Creating pufferd templates

How to add a new template

One of the main features of pufferd is its template system, which makes it very easy to add new games by simply editing a JSON file.

These templates are located by default in /var/lib/pufferd/templates

To create a new template, make a new file in /var/lib/pufferd/templates with a name not used by a default template, and make sure the file ends in .json

Template Structure

Templates are made up of a beginning description and 4 main sections: install, run, environment, and data

Variables are created in the data section and can be used throughout the template with the syntax ${variable} to replace data where needed.

type: To start, include the beginning section which includes the "type" of template it is. This type field is not utilized yet, but will be in the future for grouping of templates.

For this example we are going to make a template for SpongeForge, so the type is set to "java" like the other Minecraft templates.

display: This sets the name of the template displayed in PufferPanel.

{
  "pufferd": {
    "type": "java",
    "display": "SpongeForge - Minecraft",

Processors

A "processor" is a command or operation that can occur on installing, before starting, and after stopping a server. Processors are made up of different times, each one having a specific job.

These types are:

  • download
  • move
  • command
  • writefile
  • mkdir

Each processor has access to each data variable defined, and can use their values. They also have the environment variables which can be defined in the run section below.

download - Downloads a file or multiple files

    "install": {
      "commands": [
        {
          "type": "download",
          "files": [
            "http://files.minecraftforge.net/maven/net/minecraftforge/forge/${forgeversion}/forge-${forgeversion}-installer.jar",
"http://files.minecraftforge.net/maven/org/spongepowered/spongeforge/${spongeversion}/spongeforge-${spongeversion}.jar"
          ]
        },

move - renaming a file - move can be used to either move a file into a different location, or rename a file. In this case we are renaming a file that begins with "forge-" to "installer.jar" so that the commands below will work even if the version of Forge changes.

        {
          "source": "forge-*.jar",
          "target": "installer.jar",
          "type": "move"
        },

mkdir - Creates a new directory

        {
          "target": "mods",
          "type": "mkdir"
        },

move - moving a file - This is moving a file that begins with "spongeforge-" into the newly created mods directory

        {
          "source": "spongeforge-*.jar",
          "target": "mods",
          "type": "move"
        },

command - Executes a command directly on the system
You should use this type only when necessary, and if possible, make the commands generic to the host operating system.

        {
          "commands": [
            "java -jar installer.jar --installServer"
          ],
          "type": "command"
        },

writefile - Writes text into a file, ${ip} and ${port} are variables from the data section

        {
          "type": "writefile",
          "text": "server-ip=${ip}\nserver-port=${port}\n",
          "target": "server.properties"
        },

move - Finally, we rename a file that begins with "forge-" and ends in "-universal" to the "server.jar" like other pufferd Minecraft templates do.

        {
          "source": "forge-*-universal.jar",
          "target": "server.jar",
          "type": "move"
        }
      ]
    },

Run

The run section defines what happens when the start and stop buttons are pressed.

stop - Command to send to the console of the running server to stop it
pre - Processors to run before the server starts
post - Processors to run after the server starts
arguments - These are the command line arguments placed after the initial program and accepts variables from the data section
program - The actual program to execute to run the server
environmentVars - Any environment variables to set for this server

{
    "run": {
      "stop": "stop",
      "pre": [],
      "post": [],
      "arguments": [
        "-Xmx${memory}M",
        "-jar",
        "server.jar"
      ],
      "program": "java"
    }
}

Pre and post support the processors defined in the above section.

Environment variables are a simple key-value mapping. An example of this section is below:

{ 
  "environmentVars": {
    "NAME": "VALUE"
  }
}

Environment

The environment section supports several types, which can be either standard, tty, or docker.

The standard environment runs the server directly on the system, as if you were running it from the command line.

    "environment": {
      "type": "standard"
    },

The tty environment is very similar to the standard environment, except it starts a pseudoterminal for the server's output to piped into. This is useful for programs that use ncurses, or otherwise do not function in the standard environment. Use it only when necessary.

    "environment": {
      "type": "tty"
    },

The docker environment runs the server in it's own container. The docker environment lets you also specify the image name to use to generate the container. If none is specified, then pufferpanel/generic is used.

    "environment": {
      "type": "docker",
      "image": "pufferpanel/minecraft"
    },

Data

The data section contains the variables used throughout the template, which can be populated by the user on the server creation page, or exist only in the template.

Each variable is made up of several options and can be used throughout the template with the syntax ${variable} to replace data where needed.

memory - This is the name of the variable, change this for each variable
value - The default value for the variable
required - Whether or not the variable must be populated
desc - The description of the variable shown on the server creation page
display - The name of the variable shown on the server creation page
internal - Whether or not to show the variable on the server creation page

    "data": {
      "memory": {
        "value": "1024",
        "required": true,
        "desc": "How much memory in MB to allocate to the Java Heap",
        "display": "Memory (MB)",
        "internal": false
      },

Finished Template

For reference, here is the entire completed template

{
  "pufferd": {
    "type": "java",
    "display": "SpongeForge - Minecraft",
    "install": {
      "commands": [
        {
          "type": "download",
          "files": [
            "http://files.minecraftforge.net/maven/net/minecraftforge/forge/${forgeversion}/forge-${forgeversion}-installer.jar",
            "http://files.minecraftforge.net/maven/org/spongepowered/spongeforge/${spongeversion}/spongeforge-${spongeversion}.jar"
          ]
        },
        {
          "source": "forge-*.jar",
          "target": "installer.jar",
          "type": "move"
        },
        {
          "target": "mods",
          "type": "mkdir"
        },
        {
          "source": "spongeforge-*.jar",
          "target": "mods",
          "type": "move"
        },
        {
          "commands": [
            "java -jar installer.jar --installServer"
          ],
          "type": "command"
        },
        {
          "type": "writefile",
          "text": "eula=${eula}",
          "target": "eula.txt"
        },
        {
          "type": "writefile",
          "text": "server-ip=${ip}\nserver-port=${port}\n",
          "target": "server.properties"
        },
        {
          "source": "forge-*-universal.jar",
          "target": "server.jar",
          "type": "move"
        }
      ]
    },
    "run": {
      "stop": "stop",
      "pre": [],
      "post": [],
      "arguments": [
        "-Xmx${memory}M",
        "-jar",
        "server.jar"
      ],
      "program": "java"
    },
    "environment": {
      "type": "standard"
    },
    "data": {
      "memory": {
        "value": "1024",
        "required": true,
        "desc": "How much memory in MB to allocate to the Java Heap",
        "display": "Memory (MB)",
        "internal": false
      },
      "ip": {
        "value": "0.0.0.0",
        "required": true,
        "desc": "What IP to bind the server to",
        "display": "IP",
        "internal": false
      },
      "port": {
        "value": "25565",
        "required": true,
        "desc": "What port to bind the server to",
        "display": "Port",
        "internal": false
      },
      "eula": {
        "value": "false",
        "required": true,
        "desc": "Do you (or the server owner) agree to the <a href='https://account.mojang.com/documents/minecraft_eula'>Minecraft EULA?</a>",
        "display": "EULA Agreement (true/false)",
        "internal": false
      },
      "spongeversion": {
        "value": "1.11.2-2282-6.1.0-BETA-2343",
        "required": true,
        "desc": "Version of Sponge to install (may be located <a href='https://www.spongepowered.org/downloads/spongeforge/stable/'>here</a>",
        "display": "Sponge Version",
        "internal": false
      },
      "forgeversion": {
        "value": "1.11.2-13.20.0.2298",
        "required": true,
        "desc": "Version of Forge to install (use version specified by Sponge)",
        "display": "Forge Version",
        "internal": false
      }
    }
  }
}

Did this page help you?