Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Fault Tolerance and OTP

OTP applications and releases

Package Erlang code as an OTP application: the .app resource file, the application behaviour callback, environment variables, dependencies, and building releases.

So far you have written modules and started their processes by hand. Real systems are packaged as OTP applications: a named unit with a defined start and stop, a supervision tree, configuration and dependencies. Several applications are then combined into a release, a self-contained, bootable system with its own runtime. This lesson shows both.

What an application is

An application has three parts:

  1. A resource file my_app.app describing it (name, version, modules, dependencies, environment).
  2. A callback module with the application behaviour, whose start/2 starts the top supervisor.
  3. The code itself: the supervisor, the workers and any helper modules.

The standard directory layout, which rebar3 creates for you (see rebar3 projects):

TEXT
my_app/
  src/
    my_app.app.src
    my_app_app.erl
    my_app_sup.erl
    my_app_worker.erl
  rebar.config

The resource file

src/my_app.app.src is a template; the build fills in the module list.

ERLANG
{application, my_app,
 [{description, "A small example service"},
  {vsn, "0.1.0"},
  {registered, [my_app_sup]},
  {mod, {my_app_app, []}},
  {applications, [kernel, stdlib]},
  {env, [{port, 8080}, {greeting, "hello"}]},
  {modules, []}
 ]}.
  • mod names the callback module and the argument for its start/2. Without mod, it is a library application: just code, nothing to start.
  • applications lists applications that must be started before this one. kernel and stdlib are always needed.
  • env holds configuration, read at run time.
  • registered lists the names the app registers, so tools can detect clashes.

The callback module

ERLANG
-module(my_app_app).
-behaviour(application).

-export([start/2, stop/1]).

start(_StartType, _StartArgs) ->
    my_app_sup:start_link().

stop(_State) ->
    ok.

start/2 must return {ok, Pid} (the pid of the top supervisor) or {ok, Pid, State}. stop/1 runs after the supervision tree has been shut down and only needs to clean up outside things.

Starting and configuring

ERLANG
1> application:ensure_all_started(my_app).
{ok,[my_app]}
2> application:get_env(my_app, port).
{ok,8080}
3> application:get_env(my_app, missing, default).
default
4> application:which_applications().
[{my_app,"A small example service","0.1.0"}, {stdlib,...}, {kernel,...}]
5> application:stop(my_app).
ok

ensure_all_started/1 also starts dependencies. In code read configuration with application:get_env/2,3 or application:fetch_env/2 (crashes if missing, which is often the right choice).

Configuration can be overridden without recompiling, using a sys.config file for a release:

ERLANG
%% config/sys.config
[
  {my_app, [{port, 9090}]},
  {kernel, [{logger_level, info}]}
].

Application start types

When an application is started you can ask for permanent (if it terminates, the whole node shuts down), transient (the node stops only on abnormal exit) or temporary (the default: the exit is only reported). Production releases normally run their main applications as permanent: if the top supervisor gives up, the node exits and an operating system supervisor (systemd, Docker) restarts everything.

From code to running system

.app file Describes the application
Supervision tree Started by start/2
Environment get_env and sys.config
Release Apps plus runtime in one folder

Applications are the unit of deployment and of dependency.

1 / 2

Releases

A release bundles the Erlang runtime (ERTS), your applications and their dependencies, plus start scripts. The target machine does not need Erlang installed. With rebar3 and a relx section:

ERLANG
%% rebar.config
{relx, [
    {release, {my_app, "0.1.0"}, [my_app, sasl]},
    {mode, prod},
    {sys_config, "config/sys.config"},
    {vm_args, "config/vm.args"}
]}.
TEXT
$ rebar3 release          # builds _build/default/rel/my_app
$ _build/default/rel/my_app/bin/my_app foreground
$ _build/default/rel/my_app/bin/my_app remote_console
$ rebar3 as prod tar      # a deployable tarball

vm.args sets the node name, cookie and emulator flags (-name my_app@host, -setcookie ..., +P 2000000). remote_console attaches an Erlang shell to the running system for inspection, an unusual and powerful way to debug production, and sasl provides release handling and progress reports. Releases also support hot upgrades with .appup files that describe how to migrate running processes, though many teams prefer rolling restarts for simplicity.

Run it: application start order as a stand-in

OTP itself cannot run on this site, so this is a JavaScript stand-in showing how ensure_all_started resolves dependencies and starts each application once, in the right order.

JS Stand-in: ensure_all_started

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Forgetting dependencies in applications: the app starts in a shell where the library happens to be loaded, then fails in a release.
  • Doing slow work in start/2: the node waits for it; start the tree quickly and finish set-up inside the workers.
  • Hard-coding configuration instead of get_env: you then must recompile to change a port.
  • Reading environment at compile time with a macro when you meant run time.
  • No sasl in the release: you lose progress and crash reports.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the mod key in the .app file do?

    {mod, {Module, Args}} makes Module:start/2 run with Args; without it the application is only a library.
  2. 2. What must application callback start/2 return?

    The application master needs the supervisor's pid so it can shut the tree down later.
  3. 3. Which call starts an application and all its dependencies?

    ensure_all_started/1 starts the listed dependencies first, in order.
  4. 4. What is a release?

    A release can run on a machine without a separate Erlang installation.

Summary

  • An OTP application = resource file + callback module + supervision tree.
  • applications lists what must start first; env holds configuration read with application:get_env.
  • start/2 returns the top supervisor's pid.
  • Start types (permanent, transient, temporary) decide what happens to the node if the app stops.
  • A release bundles runtime, apps and config; rebar3 release builds it.

Next: Distributed nodes