haljin / config_tuples

Distillery's config provider to replace config tuples

ConfigTuples for Distillery releases

ConfigTuples provides a Distillery config provider that replaces config tuples (e.g {:system, value}) with their expected runtime value.

Usage

Documentation can be found at https://hexdocs.pm/config_tuples.

Add the package by adding config_tuples to your list of dependencies in mix.exs:

def deps do
  [
    {:config_tuples, "~> 0.2.0"}
  ]
end

Then, add it to the config providers of distillery in rel/config.exs

release :myapp do
  # ...snip...
  set config_providers: [
    ConfigTuples.Provider
  ]
end

This will result in ConfigTuples.Provider being invoked during boot, at which point it will evaluate the current configuration for all the apps and replace the config tuples when needed, persisting it in the configuration.

Config tuples

The config tuple always start with :system, and can have some options as keyword, the syntax looks like this:

• {:system, env_name}
• {:system, env_name, opts}

The available options are:

• type: Type to cast the value, one of :string, :integer, :atom, :boolean. Default to :string
• default: Default value if the environment variable is not set. Defaults no nil
• transform: Function to transform the final value, the syntax is {Module, :function}
• required: Set to true if this environment variable needs to be set, if not set it will raise an error. Defaults to false

If you need to store the literal values {:system, term()}, {:system, term(), Keyword.t()}, you can use {:system, :literal, term()} to disable ConfigTuples config interpolation. For example:

# This will store the value {:system, :foo}
config :my_app,
  value: {:system, :literal, {:system, :foo}}

Config tuples will replace your values inside of maps and lists (See the trade-offs section for lists)

Example

This could be an example for the main app, Ecto repository and logger:

config :my_app,
  uri: {:system, "HOST", transform: {MyApp.UriParser, :parse}, required: true}

config :my_app, MyApp.Repo,
  adapter: Ecto.Adapters.MySQL,
  username: {:system, "DATABASE_USERNAME", default: "root"},
  password: {:system, "DATABASE_PASSWORD", default: "toor"},
  database: {:system, "DATABASE_DB", default: "myapp"},
  hostname: {:system, "DATABASE_HOST", default: "localhost"},
  port: {:system, "DATABASE_PORT", type: :integer, default: 3306},
  pool_size: {:system, "DATABASE_POOL_SIZE", type: :integer, default: 10}

config :logger,
  level: {:system, "LOG_LEVEL", type: :atom, default: :info}

Known trade-offs

Module attributes

Sometimes in our apps we fetch the configuration values with module attributes, for example:

defmodule MyApp do
    @port Application.fetch_env!(:my_app, :port)

    # Use @port
end

When releasing your app with Distillery, your code is compiled when you execute mix release, and the config providers are executed just before booting your code.

This means that if you use module attributes for loading values expected to be replaced by any config provider, it won't be replaced, because that value will be setted on compile time, when doing the release (You can read more about module attributes here)

Instead of module attributes you can use the following code:

defmodule MyApp do
    defp port, do: Application.fetch_env!(:my_app, :port)

    # Use port()
end

Tuples inside of lists

ConfigTuples works recursively in maps and lists, which makes it unable to differenciate a keyword list (like the app config) with an element of the list with a 2-tuple, if you need to trigger ConfigTuples inside a list you need to pass some option as third parameter:

# Assuming that HOST=localhost
# :value option will have [{:system, "HOST"}, "localhost"]
config :my_app,
  value: [{:system, "HOST"}, {:system, "HOST", type: :string}]