Releases shouldn't be a pain to build and run -- especially since you have all the necessary pieces sitting right there! -- and we've done our best to make that no longer the case.

Add a relx section to your project's rebar.config:

Running rebar3 release will build the release and provide a script for starting a node under _build/<profile>/rel/<release name>/bin/<release name>.

<release_name> must be an atom, same for each <app> in the list of applications to include in the release.

<vsn> can be one of:

You can add multiple release sections to your project's rebar.config under relx.
You can either just specify different releases sharing the same configuration:

Or you can also specify releases with independent configurations:

You can build specific releases using rebar3 release -n <release_name>

While developing you'll likely want all your changes to applications be immediately available in the release. relx provides dev_mode for this. Instead of copying the applications that make up the release to the release structure it creates symlinks, so compiling and restarting or loading the changed modules, is all that is necessary.

VM Configuration

By default relx will give a basic vm.args file that sets a node name and cookie. For a complete list of options and their use check the Erlang documentation.

To provide a custom vm.args, usually placed in the config/ directory at the root of your project, add this line to the relx section of your rebar.config:

Application Configuration

For passing application environment variables there is sys.config:

The default sys.config is empty, so use your own simply add it to your relx section of rebar.config:

With OTP-21+ and rebar3 3.6+

Starting with Erlang/OTP 21 and rebar3 3.6.0 the configuration options sys_config_src and vm_args_src are available for explicitly including templates that will be rendered at runtime.

Note that, unlike previous versions, if you use the _src variants you do not have to set RELX_REPLACE_OS_VARS in order for the start script to do the replacement, this will happen automatically if the .src files are present in the release.

Before OTP-21 and rebar3 3.6

By setting RELX_REPLACE_OS_VARS=true both vm.args and sys.config files may contain OS environment variables that will be replaced with the current value from the environment the node is started in. This means a vm.args and sys.config for a release that starts a web server listening on a port could look like:

And then be used to start multiple nodes of the same release with different name.

Overlays provide the ability to define files and templates to include in the target system. For example, custom scripts for managing your node or the Procfile needed for running on Heroku.

The supported actions are:

• mkdir to create a directory within the release
• copy to copy a file from a local directory to a location within the release
• template to behave the way copy does, but with variable expansion in it.

Relx's templating exposes variables along with the full power of a Mustache templating system (see mustache). You can look at the documentation there for the full syntax supported.

There is a set of variables made available by default which are described in the next session, and custom variables can otherwise be declared in the file specified in {overlay_vars, "vars.config"}, which should have the following format:

The default variables are defined below.

Predefined variables

• log : The current log level in the format of (<logname>:<loglevel>)
• output_dir : The current output directory for the built release
• target_dir : The same as output_dir, exists for backwards compatibility
• overridden : The current list of overridden apps (a list of app names)
• goals : The list of user specified goals in the system
• lib_dirs : The list of library directories, both user specified and derived
• config_file : The list of config file used in the system
• providers : The list of provider names used for this run of relx
• sys_config : The location of the sys config file
• root_dir : The root dir of the current project
• default_release_name : The current default release name for the relx run
• default_release_version : The current default release version for the relx run
• default_release : The current default release for the relx run
• release_erts_version : The version of the Erlang Runtime System in use
• erts_vsn : The same as release_erts_version (for backwards compatibility)
• release_name : The currently executing release
• release_version : the currently executing version
• rel_vsn : Same as release_version. Exists for backwards compatibility
• release_applications : A list of applications included in the release

Splitting configurations

It is possible to split overlay files to deal with more complex situations. To explain this lets look at the a simplified example:

We build our application and want to distinguish between production and developing builds by having the overlay variable build spell out either "prod" or "dev" so the app.config file could include it in it's configuration and we can either enable or disable features.

For this we build three overlay files:

• a dev.config - that is dev branch specific
• a prod.config - that is prod branch specific
• a base.config - that is not branch specific

For dev builds we will use dev.config as overlay_vars and for prod we will be using prod.config.

To build a release capable of being copied to other nodes we must turn off dev_mode so applications are copied to the release lib dir instead of being symlinks.

Or create a profile that turns off dev_mode:

Target System

A target system can not have symlinks like those created when using dev_mode and often we want to include ERTS along with the system so it does not need to be previously installed on the target.

Now we can also build a compressed archive to copy to the target:

Now a tarball myrel-0.1.0.tar.gz can be copied to another compatible system and booted:

Without Erts

To use the ERTS and base applications like kernel and stdlib on the target, set include_erts and system_libs to false in the relx configuration tuple:

By default the release will include source files of your applications, if present.
If you don't want to include the source files, set include_src to false.

The following allows you to remove specific applications from the output release.

The following directive allows you to remove application modules from the output release.

If you wish to include an Erlang Run Time System that is not the version you are using to run rebar3, for example you are building on MacOSX but wish to include an ERTS that was built for a version of GNU/Linux, you can supply a path instead of a boolean for include_erts and provide a path for system_libs, still within the relx configuration tuple:

Using these paths with profiles can yield easier ways to set up cross-compiling.

It is possible to define hooks on specific operations of the extended start script, the operations are start, stop, install_upgrade, pre and post hooks for each of these operations are available.

The hooks can either be builtin (ie. they are already included in the release) or custom (scripts written by the user for custom functionality), the builtin scripts offer pre-packaged functionality, they are:

• pid : Writes the beam pid to a configurable file location
  (/var/run/<rel_name>.pid by default).
• wait_for_vm_start : Waits for the vm to start (ie. when it can be pinged).
• wait_for_process : Waits for a configurable name to appear in the Erlang process registry.

The extended start script that is generated comes with a builtin set of commands that allows you to manage your release, these are start, stop, restart, etc.

Sometimes it's useful to expose some custom commands that are specific to your application. For example if you're running a game server it would be convenient to just call bin/gameserver games that outputs useful information.

Extended start script extensions allow you to create a custom shell script that gets appended to the list of commands available to your start script. The extension shell script can take arguments and has access to all shell variables defined in the start script itself. You begin by defining the extension in your rebar.config, for example:

Here you are adding the status script extension that will invoke an extensions/status shell script.
This path is relative to the location of the start script on the generated release so you probably will want to use a overlay to place it at the correct location:

The extension script itself is standard shell script, the game server example described could be implemented in the following way:

The extended start script that comes with relx and is set to be used by rebar3's release template, {extended_start_script, true}, provides a few ways of starting and connecting to your release.

For local development you'll like use console. In production you'll want start or foreground.

start creates a pipe that can be connected to later with the command attach. The Erlang VM calls fsync on every line of output in this mode, so foreground might be better for your use cases.

To open a console with a node started with foreground use remote_console.

Appup generation

Using relflow

For a detailed workflow including version increments and appup generation checkout Richard Jones relflow tool built around rebar3.

Deploying an upgrade

For the basic release upgrade after install of a release assume we have a release named myrel with a version 0.0.1 and 0.0.2:

• Installing: Installing a release on a running system will unpack and upgrade the version: bin/myrel install 0.0.1
• Listing: you can inspect what versions are currently available: bin/myrel versions
• Upgrading: If the version is already unpacked you can simply call upgrade to upgrade to the version: bin/myrel upgrade 0.0.2
• Downgrading: To downgrade to the previous version use the downgrade command: bin/myrel downgrade 0.0.1

• relx
• relflow
• Releases chapter from Learn You Some Erlang
• OTP release documentation
• OTP target system documentation