Creating and Using a Custom Package

This tutorial shows how to create an Apcera package from a third-party NPM module and then use your custom package in an application. For this tutorial you will create a package from Node-RED, a Node module that provide a visual tool for wiring together devices, APIs and services.

Create the Custom Package

To create a package you use a package script. A package script contains metadata about the package, and a build script block. Metadata includes the package name and version, any dependencies it requires or provides that it can satisfy, and any environment variables to set on the package. The build script block contains Bash commands that perform any additional tasks to prepare the package to run.

To deploy Node-RED as a package:

  1. In a new project folder create a text file named node_red.conf with the following text:

     name:       "node-red"
     version:    "0.10.10"
     build_depends [ { package: "build-essential" },
                     { runtime: "node-0.10.30" } ]
     depends       [ { os: "linux" },
                     { runtime: "node-0.10.30" } ]
     provides      [ { package: "node-red-0.10" },
                     { package: "node-red-0.10.10" } ]
     environment {   "PATH": "$PATH:/usr/local/bin",
                     "NODERED_HOME": "/opt/node-red/node_modules/node-red" }
     build (
    
         export INSTALLPATH=/opt/node-red
         (
             mkdir -p $INSTALLPATH
             cd $INSTALLPATH
             npm install node-red@0.10.10
         )
     )
    

    This is a package script. Let's examine the contents of this script:

    • name and version fields define the package's name and version.
    • build_depends specifies the dependencies required to build the package. In this case, it requires a specific version of node (0.10.30) as well as the build-essential package that's provided with Apcera to assists with build tasks. These packages are removed once the build has finished.
    • depends specifies the dependencies required to run the package; in this case it requires Linux and Node.
    • providers specifies the capabilities that the package can satisfy to other packages.
    • environment specifies environment variables to set on the package's environment. In this case, we append /usr/local/bin to the existing PATH variable and set a variable named NODERED_HOME to the location where the node-red module is installed. As you'll see next, an Application that uses this package needs this location to know how to start the module.
    • The build property is a block of bash statements delineated by a pair of parentheses. The closing parenthesis must be the first and only character of the final line of the block. In this case, the build script creates a folder to install the module, changes to that directory and runs npm install.
  2. Save your changes to node-red.conf and build the package:

     apc package build node-red.conf
    

    This create the package in your current (default) namespace. To better organize your packages, you can include the --namespace (or -n) option. For example, the following command creates the new package in the /dev/packages namespace.

     apc package build node-red.conf -ns /dev/packages
    

When the build process has completed successfully you should see the message "Created package "package::/sandbox/user/packages::node-red".

The actual namespace ("/sandbox/user" in this case) will be different for your environment, or depending if you specified a custom namespace for the package. Next you'll create an application from the package you created.

Create an Application from the Package

Next you'll create an application that depends on the package you just created. To deploy the application you'll use an application manifest, a plain text file that defines a set of deployment attributes. All options in a manifest can also be declared as APC options on the command line. The main benefit of a manifest is that it provides easily reproducible application deployment settings.

To create an application from the new package:

  1. Create a text file named node-red-app.conf and add the following text to it. This is the application manifest. You will need to make some changes to attribute values in this file to match your environment:

    • Change the namespace value to match the desired namespace for the application.
    • Change the route endpoint value to match your Apcera cluster name and top-level domain. See in-line comments below for details.

        name: "node-red-app"
        # Change namespace to where app should be located.
        namespace: "/sandbox/user"
        staging_pipeline: "/apcera::nodejs"
        start_cmd: "sudo node $NODERED_HOME/red.js"
        package_dependencies: [ "package.node-red-0.10.10" ]
        # Change the endpoint URL to match your environment. e.g. endpoint: "node-red.yourname.sandbox.continuum-demo.io"
        ports: [
            {
                number: 1880,
                routes: [
                    {
                        type: "http",
                        endpoint: "node-red.user.sandbox.continuum-demo.io"
                    }
                ]
            }
        ]
        start: true
      

    Note the following about this manifest:

    • The staging_pipeline attribute specifies the built-in nodejs stager using its fully qualified name ("/apcera::nodejs"). By default, the staging coordinator picks the correct staging pipeline based on the presence of specific source files (for instance, a package.json file). In this case we're creating the application directly from a deployed package without any source code, so we must specify the right pipeline to use.
    • The package_dependencies attribute specifies the package(s) the app needs to run, which in this case is the package you just created. The package name is prefixed by "package" (can also be "runtime" or "os", depending on the package type).
    • The start_cmd specifies the command to start the application. Note that it uses the NODERED_HOME environment variable (set by the package script) to locate the correct entry point (red.js).
    • The ports attribute exposes the port where the application is listening and the route (URL) where it can be accessed from a web browser. By default, the Node-RED module serves its UI on port 1880, which the route is mapped to.
    • The start: true pair tells Apcera to start the app immediately after it's successfully staged.
  2. Create the application by calling apc app create and passing it the name of the manifest to use using the --config option:

     apc app create --config node-red-app.conf
    

    Once complete, you should see the following console message (with a different URL):

     App should be accessible at "http://node-red.user.sandbox.continuum-demo.io"
    

    Open the provided URL in your browser to see the Node-RED interface running.