Deployment Scripts

Overview

Deployment Scripts are a feature available free-of charge on all Mammoth VPS that can provide automated setup of new software, configuration of preferred defaults, and general customisation of the VPS.

Screenshot of of a reinstall using the "LAMP Stack" script (click to view)

When using a deployment script, the selected script can ask for configuration values through mPanel (such as the MySQL root password, in the example above). Upon giving your confirmation, the script and its configuration values are written into the VPS. As the VPS boots up, the rescue console is shown so that you may monitor the progress of the script.

A variety of pre-written scripts by Mammoth and other customers are available for selection, or you can create your own in mPanel. Scripts can be kept private to your account, or shared with other Mammoth customers.

Deployment Script library

Development Guide

Deployment scripts can be written in using any language interpreter that the distribution has installed - typically Bash, Python, or Perl. During deployment, the script is written into the VPS and temporarily replaces the standard Linux console login prompt (getty/mingetty). In other words, the script executes after all daemons and system services have been started when the system is ready for interactive use.

A script can specify that it supports particular environment parameters, as you might set in the shell via MYVAR=value. After selecting the script in mPanel, the script user is prompted to supply values for each of the environment parameters the script supports.

When developing multiple deployment scripts, you may find that you have a common core of functionality that is used in each script. Instead of repeating this functionality in each script, it can be defined in a separate script and then referenced through an include directive.

Creating a script

To start creating a deployment script, login to mPanel and go to the Deployment Scripts section. After clicking the "Add" button, fill out the form as follows:

• Name: Used as the identifier of the script throughout mPanel. It is used when selecting which script to deploy and for locating the script for editing at a later date.
• Description: Explains what the script does and any special requirements it has. This is displayed in mPanel after selecting the script for deployment, and in the script browser if you choose to publish the script for other Mammoth customers to use.
• Deployable: When checked (which is the default), indicates that the script is available when selecting a deployment script to use. Clear this checkbox if the script is not yet ready for use, or if the script is only intended for use via an include directive (that is, it does not actually do anything if executed on its own).
• Supported distributions: Each distribution supported by Mammoth is listed. When selecting a deployment script for deployment, only those scripts which support the distribution being deployed to are displayed - for example, this prevents deploying a script on Fedora if the script does not indicate that it supports Fedora.
• Script: This is the actual script itself, whether it be Bash, Python, Perl, or another language. The script must start with a hashbang line indicating which interpreter to use, e.g. #!/bin/bash. The script can contain env and/or include directives, which are explained below.
• Changelog entry: This is only displayed within the script editor; when making revisions to a script it can be used to indicate why the change is being made. The script editor will store this along with a unified diff showing what lines were changed in each revision.
• Publish: If selected, a published script is available for selection by all Mammoth customers. If left unselected (the default), the script is private to your account. This intersects with the "Deployable" flag; if a file is published but not deployable, it can be included by other users but is not deployable on its own.
• Author: A handle or domainname identifying the author of a published script; this is listed before the script's name during selection. For example, entering "mammoth" will result in "mammoth's LAMP Stack".
• File ID: This is a unique identifier like "lamp-stack", for referencing this file in include directives. As the identifier is unique across the system, it can be useful to prefix it with something identifying the author, like "mammoth-lamp-stack".
• External ID: If this script comes from another system that uses numeric identifiers instead of a unique string, you can enter it here so that the file may be included by that ID instead.

Env Directive

A script can request environment parameters by inserting<?env?> directives into the script's source code. In mPanel, these directives are displayed within the web interface and the supplied values are then passed to the script's environment during execution.

An env directive accepts a number of arguments as follows:

• name: Required. The name of the environment parameters as its seen within script during execution. The name is automatically converted to all-caps, so a <?env name="default_user" ?> is exposed to a bash script as $DEFAULT_USER. If the supplied name contains the string "password", then the input on mPanel is starred-out instead of being displayed as text.
• label: Optional. This is displayed within mPanel as the human-readable explanation of the environment parameter's purpose. For example, the following will result in mPanel prompting the script user to enter a value for "Default User:". (If omitted, the name is displayed instead.)

  <?env name="default_user" label="Default User" ?>
  

• default: Optional. Supplies a value that will be used to prefill the deployment form in mPanel. If a value for default is not supplied, then mPanel will require the script user to enter a value. A blank default is also allowed; so the following can be used to mark the field as optional without supplying any particular default:

  <?env name="default_user" default="" ?>
  

• example: Optional. This is an additional explanation about the purpose of the field. For example:

  <?env name="default_user" example="sudo user to create during deployment" ?>
  

• oneof: Optional. If specified, this should be a comma-separated list of values. mPanel will display the list as a drop-down box, requiring the user to select one of the values. For example:

  <?env name="colour" oneof="red,green,blue" default="green" ?>
  

• manyof: Optional. If specified, this should be a comma-separated list of values. mPanel will display the list in a multi-select box, allowing the user to select any combination of items (or none at all). For example

  <?env name="colour" manyof="red,green,blue" default="red,blue" ?>
  

  The selected values are supplied to the script as a comma-separated string; for example COLOUR="red,blue"

As env directives are not removed from the script during deployment, they should be commented out - usually by placing a hash at the start of the line.

Include directive

A script can request that another deployment script be written into the VPS during deployment via the <?include?> directive. Scripts can be referenced via their file ID or their external ID, e.g.

# Include by file ID
<?include file="mammoth-debian-lib" ?>
# Include by external ID
<?include file="1" ?>

During deployment, the referenced file is written to the VPS's disk and the include directive is replaced by the name of the file the script was written to. In Bash, you can include the file as follows:

#!/bin/bash
source <?include file="mammoth-debian-lib" ?>
...

Scripts referenced via an include directive cannot use env directives or include other scripts themselves; that is, they are simply written into the VPS for deployment with no processing.

Third-party compatibility

Mammoth's deployment scripts are broadly compatible with StackScripts; <udf> and <ssinclude> tags are mapped to <?env?> and <?include?> directives with the same semantics. In the general case a StackScript can be used unmodified as a deployment script as long as its includes have also been added in our system.