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 performs the following:

As was mentioned in the previous section, start_erl requires a sys.config in the release version directory ("releases/FIRST/sys.config"). If there is no such file, the system start fails. Such a file must therefore also be added.

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

However, it can also be convenient to replace variables in within a sys.config on the target after unpacking but before running the release. If you have a sys.config.src it will be included and is not required to be a valid Erlang term file like sys.config. Before running the release you must have a valid sys.config in the same directory, so using sys.config.src requires having some tool to populate what is needed and write sys.config to disk before booting the release.

The previous 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 the applications ERTS, Kernel, STDLIB and SASL.

Step 1. Create the file .rel:

Step 2. Create the application upgrade file (see the appup(4) manual page in SASL) for Pea, for example:

Step 3. From the directory where the file mysystem2.rel resides, start the Erlang/OTP system, giving the path to the new version of Pea:

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

Step 4. Create the release upgrade file (see the relup(4) manual page in SASL):

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

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

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 file relup generated in Step 4 is now located in the current directory, it is automatically 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. For more information, see Starting a Target System.

We add -heart to bin/start:

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

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

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

Assuming that the node has been started as follows:

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

It can be accessed as follows:

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

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 is always done when the upgrade involves a change of the applications ERTS, Kernel, STDLIB, or SASL. For more information, see Upgrade when Erlang/OTP has Changed.

The node is accessible through a new pipe:

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

Check which releases there are in the 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 now, it would come up running the "FIRST" release again.

Step 3. Make the new release permanent:

2> release_handler:make_permanent("SECOND").

Check 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}]

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