# How To Create Software Release

This document will guide through the steps of creating a new software release - a set of files which allow to build and instantiate a software on SlapOS. The key components of a software release are the software profile (`software.cfg`) used to build and install the software and the instance profile (`instance.cfg.in`) used for instantiation.

Both installations and instantiations are done using a software called Buildout, which utilizes the templating language Jinja2. This howto expects familiarity with both. It will introduce the different sections of a profile and show how they are put together using the Amarisoft LTE software release (gitlab repository - see `$your_repo_location/tree/master/slapos/software/lte` for the corresponding file).

Please note that this howto does not cover adding a software release to the catalogue of the NMS master or upgrading an existing software release. It also does not cover installing a software on a node.

# Table of Content

- Amarisoft LTE Software Release

# Amarisoft LTE Software Release

While there are many simple software releases consisting only of a software and instance profile, there are just as many more complex ones with a multitude of different templates and configuration files. This section will explain the Amarisoft LTE Software Release and the files it consists of to give an idea of how to write a new release or extend this existing release.

The SlapOS repository is usually contains the following three directories (among others):

- /component - pieces to include in a software profile (eg dcron, bycrpt)
- /slapos/software - software profiles utilizing components (eg LTE or SimcardDB)
- /stack - software build from multiple softwares & components (eg Amarisoft, LAMP)

# LTE Release

The `/slapos/software/lte/` repository consists of the following files:

- build.hash.cfg - list of MD5 sums for templates included in the software profile
- instance-default.jinja2.cfg - template for instantiating "lab" (default) version
- instance-enb-input-schema.json - parameter definition for instantiation of "enb"
- instance-enb.jinja2.cfg - template for instantiating "enb" software instance
- instance-eps-input-schema.json - parameter definiton for instantiation of "epc"
- instance-ims-input-schema.json - parameter definition for instantiation of "ims"
- instance-ims.jinja2.cfg - template for instantiating "ims" software instance
- instance-license-input-schema.json - parameter definition for instantiation of "licence"
- instance-license.jinja2.cfg - template for instantiating "licencse"
- instance-lte-input-schmema.json - parameter definition for instantiation of "lte"
- instance-mbms-input-schema.json - parameter definition of "mbms" installation
- instance-mbms.jinja2.cfg - template for instantiating "mbms" software instance
- instance-mme.jinja2.cfg - template for instantiating "mme" software instance
- instance.cfg - instance profile (instantiation)
- software.cfg - software profile (installation)
- software.cfg.json - definition of available software types of this software
- ue_db.py.in - Simcard DB configuration and access

# Software Profile

The `software.cfg` file is used for installation of the LTE software on a node. You can see that it mostly defines required versions of included software in the `[versions]` section.

Besides this, the templates are listed that will later provide the different software-types during instantiation. Each section:

    [template-lte-ims]
    recipe = slapos.recipe.build:download
    url = ${:_profile_base_location_}/instance-ims.jinja2.cfg
    filename = instance-ims.cfg
    mode = 0644

defines the recipe to use (in this case the download recipe), the location of the template file to use for instantiation as well as the name of the instantiation output file and its permissions.

If a section defines a context, like `[ue_db.py.in]`, it exposes parameters to the instance profile (`instance.cfg`) so that they can be used there. The `[parts]` section denotes the recipes to be excuted when Buildout runs the sofware profile, in this case the template and sdr-driver sections/recipes whereas the `[buildout]` section extends the default buildout configuration by the file containing the MD5 sums as well as Amarisoft's stack.

# Software Profile (json)

The JSON software profile is used to create forms for a software release. By convention the entry point file is found by including `.json` to the url of the software release, so `software.cfg.json`. The file is used to list the available software-types and forms (Schemas) that a user can choose during instantiation. A template for a form looks similar to this:

    {
        "name": "NAME OF Software",
        "description": "The description",
        "serialisation": "xml",
        "software-type": {
            "default": {
                "title": "Default",
                "software-type": "default",
                "description": "description of default",
                "request": "instance-NAME-input-schema.json",
                "response": "instance-NAME-output-schema.json",
                "index": 0
            },
            "default-slave": {
                "title": "Slave",
                "description": "Description for the slave",
                "software-type": "default",
                "request": "instance-NAME-slave-input-schema.json",
                "response": "instance-NAME-output-schema.json",
                "shared": true,
                "index": 1
            },
            ...
        }
    }

The most important fields are:

- "title" - name of the software-type displayed to the user
- "software-type" - defines the type of software
- "shared" - defines whether the instance is a slave of another instance (eg (slave-)tokens issued by a registry)
- "request" - the (relative) link to the file containing the json schema used to render the form

# Form Input Schema

The JSON input schema allows to define form fields of a software-type to display to the user. They will be rendered live by fetching the respective urls. For example:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "properties": {
        "somevalue": {
          "title": "Input a String",
          "description": "This is an example of string parameter",
          "type": "string"
        },
        "sonumber": {
          "title": "Input a Number",
          "description": "This is an example of number parameter",
          "type": "number"
        }
      }
    }

It is adviced to use a flat approach (one level, don't create unneccessary depth/complexity) and a simple structure. Keep in mind:

- keep it short, the larger the amount of parameters, the longer and complex is the form.
- omit entries which are set automatically or by convention (port number, etc).
- omit values that depend on other instances if value can be taken automatically.
- use prefixes for different software on same hosting subscription.
- use meaningful title and description.

# Instance Profile

The instance profile will be used to instantiate whichever software-type the user selected using the parameters the user provided filling out the template-form.

In the LTE profile you can see that `[parts]` being run are dynamic-template-lte-default and switch-softwaretype aside from the mandatory `[instance]` and `[jinja2-template-base]` sections. The dynamic-template-lte-default provides instantiation instructions for the default "lab" version of LTE, which is also one of the available software-types the user can choose from. All software types are then listed in the switch-softwaretype section.

Each software-type section defines extra content, listing the parameters and values to be exposed to the Jinja2 template:

    [dynamic-template-lte-ims]
    < = jinja2-template-base
    template = ${template-lte-ims:target}
    filename = instance-lte-ims.cfg
    extensions = jinja2.ext.do
    extra-context =
        raw monitor_template ${monitor2-template:rendered}
        ...

With the above information it should possible to re-create the LTE software release, extend or rewrite it altogether.

# Thank You

- Nexedi SA
- 147 Rue du Ballon
- 59110 La Madeleine
- France

- nexedi.com/contact