Upgrades

Rebar makes building Erlang releases easy. One of the advantages of using OTP releases is the ability to perform hot-code upgrades.

To do this you need to build a upgrade package that contains the built modules and instructions telling OTP how to upgrade your application. Those instructions come in the form of appup files and rebar can build them for you. The goal of the generate-appups command is to at the very least create a skeleton to get you started on a more complex appup, in simple cases the appup it creates will be usable without any edits. If an appup file already exists a new one will not be created. Once you have your appup files created you can build a upgrade package with the generate-upgrade command.

In the test/upgrade_project directory of the rebar repo you will find an example "dummy" release you can use as an example of how to run hot-code upgrades using rebar. The below instructions should apply closely to your release.

Building version 0.1

rebar compile
cd rel
rebar generate
mv dummy dummy_0.1
cd ..
rebar clean
# start the release:
cd rel/dummy_0.1
bin/dummy console

erl> dummy_server:get_state().
erl> dummy_server:set_state(123).
erl> dummy_server:get_state().

Building version 0.2

# Now, in another terminal we prepare an upgrade..

# change release version numbers from 0.1 to 0.2 in
$EDITOR apps/dummy/src/dummy.app.src
$EDITOR rel/reltool.config

rebar compile
cd rel
rebar generate
rebar generate-appups previous_release=dummy_0.1
rebar generate-upgrade previous_release=dummy_0.1

# Examine contents of upgrade package if you wish:
tar -zvtf dummy_0.2.tar.gz
mv dummy dummy_0.2

Deploying with release_handler

mv dummy_0.2.tar.gz dummy_0.1/releases/

# Now use release_handler in the running erlang console for the deploy:

erl> release_handler:unpack_release("dummy_0.2").
erl> release_handler:install_release("0.2").
erl> release_handler:make_permanent("0.2").

erl> release_handler:which_releases().
erl> dummy_server:get_state().

Building version 0.3

rm -r rel/dummy

# Now repeat steps in 'Building version 0.2' and 'Deploying with release_handler'
# while replacing '0.2' by '0.3' and '0.1' by '0.2'.

Caveats:

• Appup and upgrade generation do not work with zipped applications (.ez extension).
• Downgrade instructions are not currently generated, only upgrade instructions.