How to use Erlang releases with Kazoo#
Kazoo is bundled and shipped as an Erlang release.
This means Erlang/OTP's and Kazoo's code are mixed together under _rel/
, thus creating a standalone Kazoo.
relx builds the release using
* rel/relx.config.script
(this file in fact generates rel/relx.config
)
* rel/vm.args
has all the BEAM VM arguments used for running the release
* rel/sys.config
(or /etc/kazoo/app.config
when present) which defines environment values for Erlang apps.
Information on Erlang releases and live-updates: * LYSE's first chapter on releases * OTP's man page on releases
Makefile commands#
All the following commands have to be run from the root directory of the Kazoo repository.
Build the release#
make build-release
Creates rel/relx.config
, the file Relx uses then to generate the release under _rel
.
This folder contains two binaries under _rel/kazoo/bin
: kazoo
and kazoo-$VSN
.
These are the exact same binary.
Node types#
The release can be spawned as either one of the following node types:
* ecallmgr
: when booting, the VM will start the ecallmgr
application and its dependencies
* kazoo_apps
: when booting, the VM will start the kazoo_apps
application and its dependencies
Once booted, the node listens to its assigned ports, writes to the system logs, does everything Kazoo did when it wasn't a release. Releases add no scoping nor sandboxing capabilities.
REL
is the Makefile variable that stipulates the node type of the starting release.
It defaults to kazoo_apps
and is used as if calling erl
with -name
option set to $(REL)@$(hostname)
.
Start a node#
Once built, start a release in "attached mode":
make release
Which is equivalent to
ACT=console REL=kazoo_apps make release
There are different ways to start/stop a release (set the Makefile ACT
variable accordingly):
* console
(default value): starts a node killable with ^G q
* start
: creates a pipe that can be connected to later with the command attach
* attach
: show the REPL of a start
-ed node
* stop
* foreground
For local development you will likely use console
. In production you will want start
or foreground
.
The Erlang VM calls fsync
on every line of output in start
mode, so foreground
might be better for your use cases.
To open a console with a node started with foreground
, use remote_console
.
Service a production node#
If the ecallmgr
died, this would start another VM:
REL=ecallmgr ACT=start make release
When troubleshooting, this attaches a REPL to the running faulty ecallmgr
node:
REL=ecallmgr ACT=attach make release
This gracefully stops an ecallmgr
node:
REL=ecallmgr ACT=stop make release
Read a release's cookie from Kazoo's configuration#
REL=kazoo_apps make read-release-cookie
This hits /etc/kazoo/config.ini
or the file at $KAZOO_CONFIG
and reads the cookie value for release REL
.
Note: the release does not even need to be started!