Creating a new Application¶

Applications can be created from the Normal Framework Admin Console UI. When creating an application, users can start with a template by specifying the git url of an existing application. If no git url is specified, and empty application is created.

Application Filesystem Layout¶

An application packaged for deployment typically is maintained in a Git repository for version control. The runtime expects a certain structure for this filesystem; the individual files are documented below.

Application installation procedure¶

When an application installed, a number of things happen in order:

1. A new chroot and JavaScript runtime is created in Normal.
2. The git repository is cloned into /app within the chroot.
3. npm install is run to install any application dependencies.
4. The application layer is created with CreateLayer.
5. Any DeleteHook calls in /hooks-delete are executed.
6. Any UpdateHook calls in /hooks-update are executed.

Parts of an Application¶

Applications serve as containers for hooks and static files that are shared together; all hooks use the same JavaScript runtime, share npm dependencies, configuration data, and a local filesystem.

The application setup is documented as part of the CreateApplication API call. Behind the scenes, CreateApplication is called when the application is created in the management console. When packaging an application for distribution, the application options are placed in a file called app.json known as the application manifest; it is simply the json-serialized version of this CreateApplicationRequest call.

Configuration Options¶

Application configuration options allow the application to prompt the user for information necessary for the app to run; for instance, a URL of another API server, or credentials for logging into another service. The options (with possible default values) are provided within the application manifest.

For example, this part from a configuration file specifies that the application has a baseUrl configuration parameter which is a string.

{
    "options": [
    {
        "name": "baseUrl",
        "option_type": "TYPE_STRING",
        "required": true
    },
    {
        "name": "priority",
        "option_type": "TYPE_SIGNED",
        "default_value": {
            "signed": 10
        },
        "validators": [
            {
                "signed_validator": {
                    "min_value": 1,
                    "max_value": 16
                }
            }
        ]
    }
}

The configuration options allow for different data types including, strings, floating point, integers, and enumerations along with associated validation logic (e.g., for specifying a min/max value for a number).

Once configured, these options are available to users when they click the "Configure" button on the application tile.

Layer Configuration¶

Each application may create a Layer; this is useful since it allows the application to define the structure of any points it will create.

The layer definition should be placed inside of the layer key in app.json. The application service will automatically call CreateLayer when the application is installed. It's up to the application code to populate its fields for any points it creates.

Logo¶

The application can package a logo.png file in the root of its application directory; this will be displayed in the application tile to brand the app.

Included Hooks¶

An application may distribute hooks which are installed along with the application. In order to achieve this, calls to UpdateHook should be placed in the hooks-update folder. These update commands will be run during application install; see the section on Hooks for details on the structure of this call.

Since the calls to UpdateHook are made as part of application installation, any scheduled hooks will begin running after application installation.

JavaScript Dependencies¶

Required JavaScript dependencies can be placed in a package.json file. They will be installed during application installation; or when InstallDependencies is called.

Static files¶

Any files places in a static/ directory are served directly to clients over HTTP. This allows an application to include a UI, dashboard, or other component. Since the files are served from the same origin as the management console, it can access the set of Normal APIs.

At this time, any complication steps for JavaScript or CSS which are required must be performed client side or ahead-of time (not within Normal)