feat(example): add an example use

Author: zmstone

example/.gitignore

@@ -0,0 +1,21 @@
+.rebar3
+_*
+.eunit
+*.o
+*.beam
+*.plt
+*.swp
+*.swo
+.erlang.cookie
+ebin
+log
+erl_crash.dump
+.rebar
+logs
+_build
+.idea
+*.iml
+rebar3.crashdump
+*~
+bin/hocon
+rebar.lock

example/README.md

@@ -0,0 +1,31 @@
+# example
+
+An exapmple OTP application to make use of HOCON for configuration management
+
+## Quick demo
+
+```
+$ rebar3 release
+$ ./_build/default/rel/example/bin/entrypoint.sh console
+Erlang/OTP 23 [erts-11.1.8] [emqx] [64-bit] [smp:20:20] [ds:20:20:10] [async-threads:1]
+
+Eshell V11.1.8  (abort with ^G)
+1> application:get_all_env(example).
+[{listeners,#{<<"http">> => #{<<"port">> => 8080},
+              <<"https">> =>
+                  #{<<"port">> => 8083,
+                    <<"ssl">> =>
+                        #{<<"cacertfile">> => "config/ssl/ca.pem",
+                          <<"certfile">> => "config/ssl/server.pem",
+                          <<"keyfile">> => "config/ssl/server.key"}}}}]
+``
+
+## Steps to create
+
+* If not an existing project, create one with `rebar3 new umbrella <name>`
+* Add HOCON config file `config/example.hocon`
+* Add HOCON schema module `apps/example/src/example_schema.erl`
+* Add an entrypoint script (which calls generated boot script) `bin/entrypoint.sh`
+    this script helps to generate sys.config and vm.args before calling the default
+    (generated by `rebar3 release` command) boot script.
+* Include the config file and the entrypoint script in `rebar3.config`'s release overlays

example/apps/example/src/example.app.src

@@ -0,0 +1,15 @@
+{application, example,
+ [{description, "An OTP application"},
+  {vsn, "0.1.0"},
+  {registered, []},
+  {mod, {example_app, []}},
+  {applications,
+   [kernel,
+    stdlib
+   ]},
+  {env,[]},
+  {modules, []},
+
+  {licenses, ["Apache 2.0"]},
+  {links, []}
+ ]}.

example/apps/example/src/example_app.erl

@@ -0,0 +1,18 @@
+%%%-------------------------------------------------------------------
+%% @doc example public API
+%% @end
+%%%-------------------------------------------------------------------
+
+-module(example_app).
+
+-behaviour(application).
+
+-export([start/2, stop/1]).
+
+start(_StartType, _StartArgs) ->
+    example_sup:start_link().
+
+stop(_State) ->
+    ok.
+
+%% internal functions

example/apps/example/src/example_schema.erl

@@ -0,0 +1,28 @@
+-module(example_schema).
+
+-export([roots/0, fields/1]).
+
+roots() -> [myserver].
+
+fields(myserver) ->
+    [ {listeners,
+       hoconsc:mk(
+            hoconsc:map(name,
+                        hoconsc:union([hoconsc:ref(http_listener),
+                                       hoconsc:ref(https_listener)])),
+            #{mapping => "example.listeners"})
+      }
+    , {concurrent_users_limit, typerefl:integer()}
+    ];
+fields(http_listener) ->
+    [ {port, typerefl:integer()}
+    ];
+fields(https_listener) ->
+    [ {port, typerefl:integer()}
+    , {ssl, {ref, ssl}}
+    ];
+fields(ssl) ->
+    [ {cacertfile, typerefl:string()}
+    , {keyfile, typerefl:string()}
+    , {certfile, typerefl:string()}
+    ].

example/apps/example/src/example_sup.erl

@@ -0,0 +1,35 @@
+%%%-------------------------------------------------------------------
+%% @doc example top level supervisor.
+%% @end
+%%%-------------------------------------------------------------------
+
+-module(example_sup).
+
+-behaviour(supervisor).
+
+-export([start_link/0]).
+
+-export([init/1]).
+
+-define(SERVER, ?MODULE).
+
+start_link() ->
+    supervisor:start_link({local, ?SERVER}, ?MODULE, []).
+
+%% sup_flags() = #{strategy => strategy(),         % optional
+%%                 intensity => non_neg_integer(), % optional
+%%                 period => pos_integer()}        % optional
+%% child_spec() = #{id => child_id(),       % mandatory
+%%                  start => mfargs(),      % mandatory
+%%                  restart => restart(),   % optional
+%%                  shutdown => shutdown(), % optional
+%%                  type => worker(),       % optional
+%%                  modules => modules()}   % optional
+init([]) ->
+    SupFlags = #{strategy => one_for_all,
+                 intensity => 0,
+                 period => 1},
+    ChildSpecs = [],
+    {ok, {SupFlags, ChildSpecs}}.
+
+%% internal functions

example/bin/entrypoint.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# OSX does not support readlink '-f' flag, work
+# around that
+# shellcheck disable=SC2039
+case $OSTYPE in
+    darwin*)
+        SCRIPT=$(readlink "$0" || true)
+    ;;
+    *)
+        SCRIPT=$(readlink -f "$0" || true)
+    ;;
+esac
+
+ERTS_VSN="{{ erts_vsn }}"
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd -P)"
+RELEASE_ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+CONFIG_DIR="$RELEASE_ROOT_DIR/config"
+CONFIG_FILE="$CONFIG_DIR/example.hocon"
+
+find_erts_dir() {
+    __erts_dir="$RELEASE_ROOT_DIR/erts-$ERTS_VSN"
+    if [ -d "$__erts_dir" ]; then
+        ERTS_DIR="$__erts_dir";
+    else
+        __erl="$(command -v erl)"
+        code="io:format(\"~s\", [code:root_dir()]), halt()."
+        __erl_root="$("$__erl" -boot no_dot_erlang -sasl errlog_type error -noshell -eval "$code")"
+        ERTS_DIR="$__erl_root/erts-$ERTS_VSN"
+        if [ ! -d "$ERTS_DIR" ]; then
+            erts_version_code="io:format(\"~s\", [erlang:system_info(version)]), halt()."
+            __erts_version="$("$__erl" -boot no_dot_erlang -sasl errlog_type error -noshell -eval "$erts_version_code")"
+            ERTS_DIR="${__erl_root}/erts-${__erts_version}"
+            if [ -d "$ERTS_DIR" ]; then
+                ERTS_VSN=${__erts_version}
+                echo "Exact ERTS version (${ERTS_VSN}) match not found, instead using ${__erts_version}. The release may fail to run." 1>&2
+            else
+                echo "Can not run the release. There is no ERTS bundled with the release or found on the system."
+                exit 1
+            fi
+        fi
+    fi
+}
+
+## generate sys.config and vm.args
+if [ "$CONFIG_FILE" -nt "$RELEASE_ROOT_DIR/sys.conf" ]; then
+    find_erts_dir
+
+    TIME="$("$ERTS_DIR/bin/escript" "$RELEASE_ROOT_DIR/bin/hocon" generate \
+                --schema_module example_schema \
+                --conf_file "$CONFIG_FILE" \
+                --dest_dir "$CONFIG_DIR" \
+                --pa "$RELEASE_ROOT_DIR/lib/example-0.1.0/ebin")"
+
+    cp "$CONFIG_DIR/app.$TIME.config" "$RELEASE_ROOT_DIR/sys.config"
+    cp "$CONFIG_DIR/vm.$TIME.args" "$RELEASE_ROOT_DIR/vm.args"
+fi
+
+exec "$SCRIPT_DIR/example" "$@"

example/config/example.hocon

@@ -0,0 +1,14 @@
+myserver.listeners {
+    http {
+        port = 8080
+    }
+    https {
+        port = 8083
+        ssl {
+            cacertfile = "config/ssl/ca.pem"
+            keyfile = "config/ssl/server.key"
+            certfile = "config/ssl/server.pem"
+        }
+    }
+}
+myserver.concurrent_users_limit=1000

example/rebar.config

@@ -0,0 +1,37 @@
+{erl_opts, [debug_info]}.
+{deps, [
+    {hocon, {git, "https://github.com/emqx/hocon", {tag, "0.17.0"}}}
+]}.
+
+{relx, [{release, {example, "0.1.0"},
+         [example,
+          sasl,
+          hocon
+          ]},
+
+        {mode, dev},
+
+        {sys_config, false}, %% generated by hocon
+        {vm_args, false}, %% generated by hocon
+        {overlay, [
+            {mkdir, "config/"},
+            {copy, "config/example.hocon", "config/"},
+            {copy, "bin/hocon", "bin/"},
+            {template, "bin/entrypoint.sh", "bin/entrypoint.sh"}
+        ]}
+]}.
+
+{pre_hooks,
+    [ {release, "bash -c 'make -C _build/default/lib/hocon es && cp _build/default/lib/hocon/_build/es/bin/hocon bin/'"}
+    ]}.
+
+{profiles, [{prod, [{relx,
+                     [%% prod is the default mode when prod
+                      %% profile is used, so does not have
+                      %% to be explicitly included like this
+                      {mode, prod}
+
+                      %% use minimal mode to exclude ERTS
+                      %% {mode, minimal}
+                     ]
+            }]}]}.