KAZOO-4362: hopefully better docs for releases

README.md

@@ -162,47 +162,13 @@ If you have a non-US deployment, please consider sharing your system configurati
 * Once the dependencies are all here, after a fresh `git clone` just `make`.
 * When developing, one can `cd` into any app directory and run:
     * `make` (`make all` or `make clean`)
-    * `make xref` to look for calls to undefined functions (uses [Xref](//www.erlang.org/doc/apps/tools/xref_chapter.html))
-    * `make dialyze` to statically type-check the app (uses [Dialyzer](//www.erlang.org/doc/man/dialyzer.html))
+    * `make xref` to look for calls to undefined functions (uses [Xref](http://www.erlang.org/doc/apps/tools/xref_chapter.html))
+    * `make dialyze` to statically type-check the app (uses [Dialyzer](http://www.erlang.org/doc/man/dialyzer.html))
     * `make test` runs the app / sub-apps test suite, if any.
-* `make release` will generate a [deployable release](//learnyousomeerlang.com/release-is-the-word), described in `relx.config.script`
+* `make build-release` will generate a [deployable release](http://learnyousomeerlang.com/release-is-the-word)
+    * [More on using releases with Kazoo](https://github.com/2600hz/kazoo/blob/master/doc/engineering/releases.md)
 * `make sup_completion` creates `sup.bash`: a Bash completion file for the SUP command
 
-## How to Use Releases
-
-`make build-release` creates `re/relx.config` which [relx](//github.com/erlware/relx/wiki) uses to generate a standalone Erlang VM equipped with Kazoo.
-Two other files are used to declare configuration:
-    * `rel/vm.args`
-    * `rel/sys.config` (or `/etc/kazoo/app.config` when present)
-
-Once built, start a release in "attached mode":
-
-```
-$ make release
-# which is equivalent to
-$ make ACT=console REL=whistle_apps release
-```
-
-The following commands service the release:
-
-```
-$ make ACT=start REL=whistle_apps release
-```
-
-```
-$ make ACT=attach REL=whistle_apps release
-```
-
-```
-$ make ACT=stop REL=whistle_apps release
-```
-
-The release will be started with the `erl` option `-name $REL@$the-machine-hostname.tld`.
-
-Information on Erlang releases and live-updates:
-    * [LYSE's first chapter on releases](http://www.erlang.org/doc/design_principles/release_structure.html)
-    * [OTP's man page on releases](http://www.erlang.org/doc/design_principles/release_structure.html)
-
 ## Learn More
 
 * Join us at [KazooCon!](http://kazoocon.com/)

doc/engineering/releases.md

@@ -0,0 +1,83 @@
+/*
+Section: Kazoo
+Title: Releases
+*/
+
+# 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](https://github.com/erlware/relx/wiki) 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](http://erlang.org/doc/man/erl.html#emu_flags) 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](http://www.erlang.org/doc/design_principles/release_structure.html)
+* [OTP's man page on releases](http://www.erlang.org/doc/design_principles/release_structure.html)
+
+## 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
+* `whistle_apps`: when booting, the VM will start the `whistle_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 `whistle_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
+
+    make ACT=console REL=whistle_apps 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:
+
+    make REL=ecallmgr ACT=start  release
+
+
+When troubleshooting, this attaches a REPL to the running faulty `ecallmgr` node:
+
+    make REL=ecallmgr ACT=attach release
+
+
+This gracefully stops an `ecallmgr` node:
+
+    make REL=ecallmgr ACT=stop   release