Creating a Release with Rebar

One way to create an Erlang release for a project that depends on Yaws, or a set of applications that includes Yaws, is to use the rebar build tool. This page details the steps required to set up the proper directory structure for such a project, create and generate the necessary release configuration files, and how to package a release for later installation and deployment.

Rebar Templates

The easiest way to build a release that uses Yaws is to use the rebar template files found under the rebar-templates directory found at the top-level of the Yaws repository. To do this, first copy all the files in the rebar-templates directory into your $HOME/.rebar/templates directory, creating it if necessary:

$ mkdir -p ~/.rebar/templates
$ cp rebar-templates/* ~/.rebar/templates

Next, run rebar in your foo project directory to create a release project skeleton, specifying the yawsnode template so rebar knows what to create. Note also that we specify foo as the nodeid and myapp as the appid:

$ cd /path/to/foo
$ rebar create template=yawsnode nodeid=foo appid=myapp

This creates two subdirectories and a rebar.config file, described below:

holds directories for the applications that comprise the foo project
build configuration for the foo project
provides support files for creating project releases

The apps Directory

Let's assume we have a single application named myapp that depends on Yaws, and myapp and Yaws together comprise the foo project. The apps directory therefore contains a myapp subdirectory, which is a normal Erlang project directory that should contain its own rebar.config file, a src directory containing Erlang source code, etc. Since myapp depends on Yaws, its rebar.config file should specify Yaws as a dependency. Note that the yawsnode rebar template does not create any of this for you; you're expected to create your own application files yourself.

Building the Project

To build the foo project, use rebar:

$ rebar get-deps compile

This first fetches all dependencies for all the applications under the apps directory, and the compiles them along with all the apps.

Creating a Release

Once everything is compiled, you can change to the rel directory and generate a release. Prior to that, though, you might want to edit the rel/files/yaws.conf file to ensure Yaws will be configured properly for your project when you run the generated release. That file is copied into the generated release. Once you've done that, run "rebar generate" in the rel directory:

$ cd rel
$ rebar generate

Because we specified the nodeid as foo when we created the project, the generation step creates a foo directory under rel that holds the generated release. It contains an Erlang runtime along with all the standard and application-specific modules and support files needed to run your project, all in a relocatable directory structure. To package it for deployment, just tar it up:

$ cd foo
$ tar zcf ../foo.tar.gz *

This packs up the whole release into the file rel/foo.tar.gz.

Deploying the Project

To deploy your project release, copy the tar file onto the target host, unpack it into an installation directory of your choice, and then run the script to ensure any absolute paths in the release reflect the chosen installation directory. You can then run the node using the bin/foo script:

$ < login to target host, copy foo.tar.gz over >
$ cd /install/path
$ tar zxf foo.tar.gz
$ ./
$ ./bin/foo console

The final command above starts the node with an interactive shell. Once it's running, Yaws and all the other applications that comprise the project will be executing. You can alternatively start the node as a daemon by running "./bin/foo start" and later stop it with "./bin/foo stop". Run "./bin/foo" with no arguments to see all its other command-line arguments.