When creating a system using Erlang/OTP, the most simple way is to install Erlang/OTP somewhere, install the application specific code somewhere else, and then start the Erlang runtime system, making sure the code path includes the application specific code.

Often it is not desirable to use an Erlang/OTP system as is. A developer may create new Erlang/OTP compliant applications for a particular purpose, and several original Erlang/OTP applications may be irrelevant for the purpose in question. Thus, there is a need to be able to create a new system based on a given Erlang/OTP system, where dispensable applications are removed, and a set of new applications are included. Documentation and source code is irrelevant and is therefore not included in the new system.

This chapter is about creating such a system, which we call a target system.

In the following sections we consider creating target systems with different requirements of functionality:

We only consider the case when Erlang/OTP is running on a UNIX system.

In the sasl application there is an example Erlang module target_system.erl that contains functions for creating and installing a target system. This module is used in the examples below, and the source code of the module is listed at the end of this chapter.

Step 4. Install the created target system in a suitable directory.

2> target_system:install("mysystem", "/usr/local/erl-target").

The function target_system:install/2 does the following:

As was pointed out above start_erl requires a sys.config in the release version directory ("releases/FIRST/sys.config"). If there is no such a file, the system start will fail. Hence such a file has to be added as well.

If you have system configuration data that are neither file location dependent nor site dependent, it may be convenient to create the sys.config early, so that it becomes a part of the target system tar file created by target_system:create/1. In fact, if you create, in the current directory, not only the mysystem.rel file, but also a sys.config file, that latter file will be tacitly put in the appropriate directory.

The above install/2 procedure differs somewhat from that of the ordinary Install shell script. In fact, create/1 makes the release package as complete as possible, and leave to the install/2 procedure to finish by only considering location dependent files.

In this example the pea application has been changed, and so are erts, kernel, stdlib and sasl.

Step 1. Create the .rel file:

Step 2. Create the application upgrade file (see appup(4)) for pea, for example:

Step 3. From the directory where the mysystem2.rel file reside, start the Erlang/OTP system:

os> erl -pa /home/user/target_system/myapps/pea-2.0/ebin

giving the path to the new version of pea.

Step 4. Create the release upgrade file (see relup(4)):

1> systools:make_relup("mysystem2",["mysystem"],["mysystem"],[{path,["/home/user/target_system/myapps/pea-1.0/ebin","/my/old/erlang/lib/*/ebin"]}]).

where "mysystem" is the base release and "mysystem2" is the release to upgrade to.

Note that the path option is used for pointing out the old version of all applications. (The new versions are already in the code path - assuming of course that the erlang node on which this is executed is running the correct version of Erlang/OTP.)

Step 5. Create the new release:

2> target_system:create("mysystem2").

Given that the relup file generated in step 4 above is now located in the current directory, it will automatically be included in the release package.

This part is done on the target node, and for this example we want the node to be running as an embedded system with the -heart option, allowing automatic restart of the node. See Starting a Target System above for more information.

We add -heart to bin/start:

And we use the simplest possible sys.config, which we store in releases/FIRST:

Finally, in order to prepare the upgrade, we need to put the new release package in the releases directory of the first target system:

os> cp mysystem2.tar.gz /usr/local/erl-target/releases

And assuming that the node has been started like this:

os> /usr/local/erl-target/bin/start

it can be accessed like this:

os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1

Also note that logs can be found in /usr/local/erl-target/log. This directory is specified as an argument to run_erlin the start script listed above.

Step 1. Unpack the release:

1> {ok,Vsn} = release_handler:unpack_release("mysystem2").

Step 2. Install the release:

2> release_handler:install_release(Vsn).
{continue_after_restart,"FIRST",[]}
heart: Tue Apr  1 12:15:10 2014: Erlang has closed.
heart: Tue Apr  1 12:15:11 2014: Executed "/usr/local/erl-target/bin/start /usr/local/erl-target/releases/new_start_erl.data" -> 0. Terminating.
[End]

The above return value and output after the call to release_handler:install_release/1 means that the release_handler has restarted the node by using heart. This will always be done when the upgrade involves a change of erts, kernel, stdlib or sasl. See Upgrade when Erlang/OTP has Changed for more infomation about this.

The node will be accessible via a new pipe:

os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2

Let's see which releases we have in our system:

1> release_handler:which_releases().
[{"MYSYSTEM","SECOND",
  ["kernel-3.0","stdlib-2.0","sasl-2.4","pea-2.0"],
  current},
 {"MYSYSTEM","FIRST",
  ["kernel-2.16.4","stdlib-1.19.4","sasl-2.3.4","pea-1.0"],
  permanent}]

Our new release, "SECOND", is now the current release, but we can also see that our "FIRST" release is still permanent. This means that if the node would be restarted at this point, it would come up running the "FIRST" release again.

Step 3. Make the new release permanent:

2> release_handler:make_permanent("SECOND").

Now look at the releases again:

3> release_handler:which_releases().
[{"MYSYSTEM","SECOND",
  ["kernel-3.0","stdlib-2.0","sasl-2.4","pea-2.0"],
  permanent},
 {"MYSYSTEM","FIRST",
  ["kernel-2.16.4","stdlib-1.19.4","sasl-2.3.4","pea-1.0"],
  old}]

Here we see that the new release version is permanent, so it would be safe to restart the node.

This module can also be found in the examples directory of the sasl application.