Deployment Scripts are a free feature for Binary Lane Linux servers that allow you to automatically install and configure software.
A deployment script can ask for configuration values through mPanel. At bootup when the script executes, it and its configuration values are written into the server. As the server boots up, the Rescue Console is shown so that you may monitor the progress of the script.
Some pre-made scripts are available, or you can easily write your own. Scripts can be kept private to your account, or made public so other customers can use them.
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 server 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 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 supported distribution 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 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 domain name identifying the author of a published script; this is listed before the script's name during selection. For example, entering "BinaryLane" will result in "BinaryLane'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 "bl-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.
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
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.
A script can request that another deployment script be written
into the server 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="bl-debian-lib" ?> # Include by external ID <?include file="1" ?>
During deployment, the referenced file is written to the server'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="bl-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 server for deployment with no processing.
Our deployment scripts are broadly compatible with
Linode's StackScripts - for example,
<ssinclude> tags are mapped to
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.