Overlays

Overlays

Overlays as defined in Rebar are directly supported in Relx. So you can take your Overlay configuration and move it to your relx.config and it should just work. For example, you could take the following:

{overlay_vars, "vars.config"}.
{overlay, [{mkdir, "log/sasl"},
            {copy, "files/erl", "{{erts_vsn}}/bin/erl"},
            {copy, "files/nodetool", "{{erts_vsn}}/bin/nodetool"},
            {template, "files/app.config", "etc/app.config"},
            {template, "files/vm.args", "etc/vm.args"}]}.

and move it directly from your rebar.config to your relx.config and it would work in exactly the same way, except wildcards are not currently supported, but a path to a directory will copy all the content. In Relx you have more options though. Relx exposes more variables along with mustache (https://github.com/soranoba/mustache). You can look at the documentation there for the full syntax supported. The variables supported are listed below. Relx also allows you to include other overlay files from an overlay file, the syntax is the same as used in Erlang (see config).

Splitting configurations

It is possible to split overlay files to deal with more complex situations. To explain this lets look at the a simplified example:

We build our application and want to distinguish between production and developing builds by having the overlay variable build spell out either "prod" or "dev" so the app.config file could include it in it's configuration and we can either enable or disable features.

For this we build three overlay files:

• a dev.config - that is dev branch specific
• a prod.config - that is prod branch specific
• a base.config - that is not branch specific

For dev builds we will use dev.config as overlay_vars and for prod we will be using prod.config.

base.config

{data_dir, "/data/yolo_app"}.
{version, "1.0.0"}.
{run_user, "root"}.

dev.config

%% Include the base config
"./base.config".
%% The build we have
{build, "dev"}.

prod.config

%% Include the base config
"./base.config".
%% The build we have
{build, "prod"}.

Available Variables

• log : The current log level in the format of (<logname>:<loglevel>)
• output_dir : The current output directory for the built release
• target_dir : The same as output_dir, exists for backwards compatibility
• overridden : The current list of overridden apps (a list of app names)
• lib_dirs : The list of library directories, both user specified and derived
• config_file : The list of config file used in the system
• sys_config : The location of the sys config file
• root_dir : The root dir of the current project
• default_release_name : The current default release name for the relx run
• default_release_version : The current default release version for the relx run
• default_release : The current default release for the relx run
• release_erts_version : The version of the Erlang Runtime System in use
• erts_vsn : The same as release_erts_version (for backwards compatibility)
• release_name : The currently executing release
• release_version : the currently executing version
• rel_vsn : Same as release_version. Exists for backwards compatibility

Example

Your sys.config file include a custom.config file, required in your release.

{overlay, [{copy, "config/custom.config", "releases/{{release_version}}/custom.config"}]}.

Next: Dynamic Configuration