An environment is a self-installing and self-configuring virtual machine that provides a pre-defined software stack, e.g. a drupal CMS, a MySQL DB… To define an environment you need:

• A VM disk image with a base OS installation and the corresponding AppStage guest packages installed. Take
• A VM Template that defines the base VM for the environment. This template will include the base image and network interfaces
• A chef-solo JSON definition file for the environment

Then you can define your new environment with AppStage to later instantiate it or share it with other OpenNebula users.

We assume that you have already prepared a VM to be the base of the your environments. Such a VM will typically consist in a vanilla OS installation plus the AppStage guest packages. Also, this disk image must be registered in an OpenNebula datastore, and a VM Template using this image as main disk has to be defined.

You can find more information on preparing the base VM disk image, here. If you need help to define images or VM templates, you can refer to the OpenNebula documentation ( VM Images Guide and VM Templates Guide).

AppStage uses Chef node files to define the software and configurations of the environment. You can follow the chef guide to understand these files.

The node files are JSON encoded and contain the recipes that are going to be run on the VM and parameters that will be used to install and configure the software. In order to allow you to easily instantiate multiple times the same environment, AppStage let you set JSON attributes as variables, in the form:

"variable":"${NAME[|<default value>]}"

The value of $NAME can be set on VM instantiation, being “default value” its default if not explicitly specified. In this way, you can instantiate the same environment with different values for a given variable (e.g. usernames, passwords, server IP's…)

In this guide we are going to use this file:

{
  "name": "wordpress",
  "run_list": [
    "recipe[mysql::server]",
    "recipe[wordpress]"
  ],
  "wordpress": {
    "db": {
      "database": "${WP_DB_NAME|wordpress}",
      "user": "${WP_DB_USER|wordpress}",
      "password": "${WP_DB_PASSWORD|password}"
    }
  },
  "mysql": {
    "server_root_password": "${MYSQL_ROOT_PASSWORD|password}"
  }
}

Note for example that the password for the DB user is defined as a variable (you can change it when instantiating the VM) and it is given “password” as the default value:

"password": "${WP_DB_NAME|wordpress}"

Once you have saved the role definition file it can be registered in OpenNebula using AppStage. Assuming that the role file is node.json, we can use the following command to create the new environment:

<xterm> $ appstage create node.json 21 </xterm>

The number returned is the identifier to our newly registered node file. We can also specify some parameters:

We can list the environments we already have defined:

<xterm> $ appstage list

 ID             NAME
 21        wordpress
 22          my_blog

</xterm>

And show the properties:

<xterm> $ appstage show my_blog NODE 22 INFORMATION ID : 22 NAME : my_blog USER : oneadmin GROUP : oneadmin COMPATIBLE TEMPLATES: ubuntu, centos COOKBOOKS : http://some.url.com/cookbooks.tar.gz PERMISSIONS OWNER : um- GROUP : --- OTHER : --- DEFAULT VARIABLES WP_DB_NAME : wordpress WP_DB_USER : wordpress WP_DB_PASSWORD : password MYSQL_ROOT_PASSWORD : password NODE DEFINITION { "name": "wordpress", "run_list": [ "recipe[mysql::server]", "recipe[wordpress]" ], "wordpress": { "db": { "database": "${WP_DB_NAME|wordpress}", "user": "${WP_DB_USER|wordpress}", "password": "${WP_DB_PASSWORD|password}" } }, "mysql": { "server_root_password": "${MYSQL_ROOT_PASSWORD|password}" } } </xterm>

There we can see the node file and its properties. It is also handy to check the default variables. Those are the ones we can change on instantiation.

We will also be able to update the node file using appstage update <node>. A text editor will be run letting us modify the node file. Note that you'll need to update the node file to update the default values for the variables.

To instantiate an environment we will use the command:

appstage instantiate <template> <node>

This command will also let us change the variables in the node using the parameter -d. For example, the following command will instantiate the my_blog environment using the ubuntu template, and will override the default values for WP_DB_NAME and MYSQL_ROOT_PASSWORD:

<xterm> $ appstage instantiate ubuntu my_blog -d WP_DB_NAME=myblog,MYSQL_ROOT_PASSWORD=some_other_password </xterm>

Now we can check that a new VM was created using the standard OpenNebula interfaces. For example using the OpenNebula CLI:

<xterm> $ onevm list

  ID USER     GROUP    NAME            STAT UCPU    UMEM HOST             TIME
  16 oneadmin oneadmin ubuntu          pend    0      0K              0d 00h00

</xterm>

And that the contextualization contains the parameters we have provided:

<xterm> $ onevm show 16 [...] VIRTUAL MACHINE TEMPLATE CONTEXT=[ COOKBOOKS="http://some.url.com/cookbooks.tar.gz", MYSQL_ROOT_PASSWORD="some_other_password", NODE="eyJuYW1lIjoid29yZHByZXNzIiwicnVuX2xpc3QiOlsicmVjaXBlW215c3FsOjpzZXJ2ZXJdIiwicmVjaXBlW3dvcmRwcmVzc10iXSwid29yZHByZXNzIjp7ImRiIjp7ImRhdGFiYXNlIjoiJHtXUF9EQl9OQU1FfHdvcmRwcmVzc30iLCJ1c2VyIjoiJHtXUF9EQl9VU0VSfHdvcmRwcmVzc30iLCJwYXNzd29yZCI6IiR7V1BfREJfUEFTU1dPUkR8cGFzc3dvcmR9In19LCJteXNxbCI6eyJzZXJ2ZXJfcm9vdF9wYXNzd29yZCI6IiR7TVlTUUxfUk9PVF9QQVNTV09SRHxwYXNzd29yZH0ifX0=", TARGET="hdb", WP_DB_NAME="myblog" ] [...] </xterm>

These parameters will be used by the contextualization script inside the VM image and will install the described node.