• node_package ** Release 3.0.0 - Release notes

Please see [[RELEASE-NOTES.md][RELEASE-NOTES.md]] for important changes in the 3.0.0 release of node_package

** Overview

node_package is a set of RPM/Debian/Solaris templates and scripts, suitable for packaging embedded Erlang nodes.

*** Supported Operating Systems

Currently supported operating systems / distros

• Redhat / Fedora and variants
• Debian / Ubuntu and variants
• FreeBSD
• OSX
• SmartOS
• Solaris

** Use

*** Makefile Variables

**** Required Variables

The following variables need to be exported for node_package to work correctly.

• =PKG_VERSION= - The version of your application (ex: 1.2.0)
• =PKG_ID= - The full name of the package, typically ={{package_name}}-PKG_VERSION= (ex: riak-1.2.0)

**** Defaulted Variables

The following variables will have a default, but can be overriden in your application.

• =PKG_BUILD= - (Default: 1) Sets the "release" version of the build (ex: app-5.4-1 <- the '1')
• =ERLANG_BIN= - (Default: which erl) Sets the path of the current erlang binary
• =DEPS_DIR= - (Default: deps) Sets the deps directory of the project, most projects uses 'deps'. Change this if something different is used.

** Package and Script Variables

*** Package Variables The following variables describe a package and should be put in the =pkg.vars.config= file.

**** Required Variables

• =package_name= - The name of the package
• =package_install_name= - The name used in the install directories eg: /usr/lib/{{package_install_name}}. Usually the same as package_name.
• =package_shortdesc= - A short (< one line) description of the package
• =package_install_user= - The user to create and run the daemon from
• =package_install_group= - The group to create and add the above user to
• =copyright= - The copyright holder (ex: 2011 Basho Technologies, Inc)
• =license_type= - The short desciption of what license the app is under
• =vendor_name= - The name of the person or company who is releasing this package
• =vendor_url= - The website of the person or company who is releasing this package
• =vendor_contact_name= - The name of the maintainer (ex: Basho Packaging)
• =vendor_contact_email= - The email address of the maintainer (ex: packages@basho.com)
• =solaris_pkgname= - Package names for Solaris follow a naming convention of MAINTapp (ex: BASHOriak)
• =runner_wait_process= - The erlang process to wait for to determine if your app started or not. (ex: riak_core_node_watcher in riak's case)

**** Optional Variables

• =license_full_text= - If the full text of a license needs to be included, use this variable
• =deb_depends= - Dependencies you require on deb sytems. This should be a comma separated list.
• =package_desc= - A long description of the package
• =solaris_depends= - (not supported yet) Dependencies specific to the solaris package
• =package_install_user_desc= - The description of the user created for the app
• =bin_or_sbin= - Tells where to put the binaries, in /bin or /sbin (default: bin)
• =freebsd_package_category= - The subsection the package is filed under in FreeBSD (ex: in this line, "ORIGIN: db/riak" 'db' would be the package_category) This defaults to 'db' if not specified for lack of a better default.
• =debuild_extra_options= - This is added to pass extra flags to debuild
• =cuttlefish_conf= - If your app uses cuttlefish for configuration, this is the filename you are using for configuration (ex: "riak.conf")

*** Script Variables The following variables are used in the =env.sh= and =runner= scripts which can be used by reltool for =rel= and =devrel= builds. They should be set in your application's =vars.config=.

**** Optional Variables

• =runner_ulimit_warn= - The runner script will warn if ulimit -n is less than this value. This defaults to 4096 in all packages.
• =package_patch_dir= - Directory to include in erlang's load path to allow for patches to be hotloaded. By default this will be in the =platform_lib_dir= (ex: "basho-patches")
• =runner_user= - The username to run the application as
• =runner_wait_process= - Registered process to wait for to consider start a success
• =cuttlefish_conf= - This is a rare case of a repeated variable since it is used in packaging and the main runner scripts, you should have this set in both the vars.config and pkg.vars.config (sadly this was the cleanest solution).

*** Templating Order There are several templating steps done in node_package:

• pkg.vars.config from the application is used to template .template from deps/node_package/priv/templates//.template
• For all the files in .template, those files are copied and templated according to the values from .template and pkg.vars.config, with pkg.vars.config trumping values from .template. This includes vars.config, which will be used in the next templating step.
• Finally, as part of the rebar generate phase, the values from the package's rel/vars.config and node_package's vars.config are used to template any overlay files marked as a template in rel/reltool.config. Values from node_package's vars.config trump the ones from rel/vars.config.

So, if you want to have a variable persist all the way through to the final reltool step, the variable needs to be set in pkg.vars.config (or defaulted in .template) AND be present in the vars.config, so it can be applied to the reltool templates.

*** Example App

The easiest app that uses =node_package= is [[https://github.com/basho/stanchion][stanchion]] a small application that Basho uses along side Riak CS.

In particular, see:

• [[https://github.com/basho/stanchion/blob/develop/pkg.vars.config][pkg.vars.config]]
• [[https://github.com/basho/stanchion/blob/develop/Makefile#L73][makefile]]
• [[https://github.com/basho/stanchion/blob/develop/rel/reltool.config#L46][reltool.config]]

It also has custom settings in its [[https://github.com/basho/stanchion/blob/develop/rel/vars.config#L31][vars.config]] for adjusting settings in the =bin/stanchion= that comes from node_package's =runner= script.