dwyl / envar

📂 envar helps check and get environment variables in Elixir

A collection of functions for checking/getting/setting environment variables in Elixir.

Why?

We needed a way of checking that environment variables were defined and improving the developer experience when they are not.

What?

envar is our solution to a very specific problem: the developer experience when a required environment variable is undefined.

How?

Installation

Install the package by adding envar to your list of dependencies in your mix.exs file:

def deps do
  [
    {:envar, "~> 1.1.0"}
  ]
end

Usage

Load an .env file containing a line-separated list of environment variables on your localhost:

Envar.load(".env")

That will locate the .env file in your project and set each environment variable in it.

If the .env must exist e.g. in a :test context, invoke:

Envar.require_env_file(".env")

That will log an Error if the file does not exist (or can't be found):

09:10:54.103 [error] Required .env file does not exist at path: /Alex/awesome/project/.env

When you need to retrieve a specific environment variable, use the following:

DATABASE_URL = Envar.get("DATABASE_URL")

If you want to define a default/fallback value for the environment variable when it's not set, simply add it as the second argument:

DATABASE_URL = Envar.get("DATABASE_URL", "postgres://uname:pass@host:5432/dbname"")

If you need to check that a variable is set, use is_set?/1

if Envar.is_set?("Heroku") do
  # do stuff on Heroku
end

To check if any of the variables in a List are set, invoke Envar.is_set_any?/1:

if Envar.is_set_any?(~w/HEROKU FLYIO/) do
  # Do something on non-prod environment
end

Conversely, to confirm that all the environment variables in a list are set, invoke Envar.is_set_all?/1:

if Envar.is_set_all?(~w/ADMIN_EMAIL AUTH_API_KEY/) do
  # Do something with the required environment variables
end

We needed a couple more convenience functions, so we wrote them!

If you need to read an .env file and get the keys & values as a Map, invoke Envar.read/1:

iex> Envar.read(".env")
%{
  "ADMIN_EMAIL" => "[email protected]",
  "EVERYTHING" => "awesome!",
  "SECRET" => "master plan"
}

If you need just the keys of the list of environment variables in an .env file, invoke: Envar.keys/1:

iex> Envar.keys(".env")
["ADMIN_EMAIL", "EVERYTHING", "SECRET"]

And if you need just the values of the environment variables in an .env file, invoke: Envar.values/1:

iex> Envar.values(".env")
["[email protected]", "awesome!", "master plan"]

For more detail, please see docs: https://hexdocs.pm/envar/Envar.html#functions

Happy Elixir Coding! 🚀

Context

We created this module after doing a search of the Elixir (Hex.pm) ecosystem,
see: dwyl/learn-environment-variables/issues/18

There are several modules available, we wanted something very basic/specific to our needs.
We don't expect anyone else to use this; it's Open Source because that's just what we do:
/manifesto.md#open-source-always

envar's Issues

update links

http=>https

Use `Logger.alert` instead of `IO.puts` for Logging

Instead of having IO.inspect in the code, we should do it the "right" way using the Logger module: https://hexdocs.pm/logger/Logger.html

If you attempt to invoke any Logger function without requiring it, you will see the following:

** (CompileError) lib/envar.ex:25: you must require Logger before invoking the macro Logger.alert/1

Simply add the following line near the top of the file:

require Logger

Ref: https://timber.io/blog/the-ultimate-guide-to-logging-in-elixir/

Chore: ** (FunctionClauseError) no function clause matching in `System.put_env/2`

This is annoying ... I've run source .env in the project but still get this error. 🤦‍♂️
Need to investigate it when I get back to my desk. 🔍

`Envar.keys/1` should return the list of environment variable keys for an `.env` file

Recently, I found myself manually writing out a list of environment variable names
that are already described in an .env file ... 🙄

This is a horrible duplication and to be avoided!

So I figure we could just read the .env file and extract the keys.
Similar to Object.keys in JS land or Map.keys/1 here in Elixir world.

Todo ✅

• Create tests for what we expect to receive when parsing a sample .env file e.g: .env_sample 📝
• Implement Envar.keys/1 (and any helper) function(s) 🧑‍💻
• Publish new version of package to Hex.pm 📦

I expect we can borrow some code from load/1 and simply return the keys. 💭
(or maybe refactor into a reusable helper function ...)
(so it should only take a few mins to implement this ... 🤞)

update readme links

http=>https

Chore: warning: Application.get_env/2 discouraged in module body, use Application.compile_env/3

Getting the following warnings when compiling the MVP project:

warning: Application.get_env/3 is discouraged in the module body, use Application.compile_env/3 instead
  lib/plug/conn/status.ex:6: Plug.Conn.Status

warning: Application.get_env/2 is discouraged in the module body, use Application.compile_env/3 instead
  lib/plug/mime.ex:4: Plug.MIME

warning: Application.get_env/2 is discouraged in the module body, use Application.compile_env/3 instead
  lib/auth_plug.ex:22: AuthPlug

The last one is related to AuthPlug which we "control". So we should update our code.
This means we have an opportunity to create an Envar.compile_env/3 function
that proxies Application.compile_env/3 but enhances it for usability.

Envar.is_set_all?/1 should ensure that ALL environment variables in a list are set

Want to be able to confirm that all the environment variables in a list are set.
This is a suuuper-basic function that will just proxy Enum.all?/1 https://hexdocs.pm/elixir/1.13/Enum.html#all?/1

Load an `.env` file of environment variables

• Load an .env file before attempting to run an App.

We have a rudimentary version of this in:

https://github.com/dwyl/auth/blob/6466f8b212a40229fbec6e7398f33f2ecfa22a8c/priv/repo/seeds.exs#L93-L110

  # load the .env file
  def load_env() do
    path = File.cwd!() <> "/.env"
    IO.inspect(path, label: ".env file path")
    {:ok, data} = File.read(path)

    data
    |> String.trim()
    |> String.split("\n")
    |> Enum.each(fn line ->
      with line <- String.replace(line, ["export ", "'"], ""),
           [key | rest] <- String.split(line, "="),
           value <- Enum.join(rest, "=") do
        System.put_env(key, value)
      end
    end)
  end

It already does what we need so going to add some tests and see how far we can get.

Bug: function `Envar.get/1` is undefined

== Compilation error in file lib/protect/github.ex ==
** (UndefinedFunctionError) function Envar.get/1 is undefined (module Envar is not available)
    Envar.get("GITHUB_ACCESS_TOKEN")

The default should not be required.

Chore: Log a `Error` if the `.env` file does not exist on `localhost`

Currently in the Development section of auth_plug: https://github.com/dwyl/auth_plug#development
We recommend the manual steps:

Create a .env file:

cp .env_sample .env
source .env

We can eliminate these steps completely by load/1-ing the .env_sample file.
But what about a project where we want there to be an .env file present on localhost and it's not there? 🤷

Todo

• Create a new function e.g: require_env_file/1 that throws a Logger.warn if the .env file is not present.

Add Repo Badges to README.md

• Add standard repo badges to the README.md of this repo
• figure out what's going on with Codecov: https://app.codecov.io/gh/dwyl/envar/ 🤷‍♂️ 🔍

https://github.com/dwyl/envar/runs/4930190661?check_suite_focus=true

Dialyxir should be `runtime: false` ...

Getting a warning when trying to deploy an app that uses envar:
dwyl/gogs-demo#3 (comment)

At present dialyxir is in the mix.exs file as:

envar/mix.exs

Line 43 in 9b592a7

{:dialyxir, "~> 1.1"}

The docs suggest:

{:dialyxir, "~> 1.0", only: [:dev], runtime: false},

Gonna update it to avoid warnings.

Intro Logo?

At present the repo looks a bit bare/boring:

That's fine for a "utility" module like this one. But it would be nice to have a more attractive intro logo ...

Chore: Respect Logging Pref of Parent/Supervisor App

As noted by @vans163 in #36 (comment) our current approach to logging
is a little crude and could result in a lot of noise and potentially even perf issues on a high traffic app. 💭

As highlighted in https://github.com/dwyl/envar/pull/36/files#diff-c24eb47ea99dc64a5109913f247d10fd83fa57e93cd9b4609cb703552215c901 there are 4 instances of Logger calls:

envar/lib/envar.ex

Lines 31 to 33 in 03b035d

	if is_nil(val) do
	Logger.error("ERROR: #{varname} Environment Variable is not set")
	end

envar/lib/envar.ex

Lines 55 to 58 in 03b035d

	case System.get_env(varname) do
	nil ->
	Logger.debug("#{varname} Environment Variable is not set")
	false

envar/lib/envar.ex

Lines 165 to 170 in 03b035d

	if File.exists?(path) do
	load(filename)
	else
	Logger.error("Required .env file does not exist at path: #{path}")
	:error
	end

envar/lib/envar.ex

Lines 199 to 202 in 03b035d

	def read(filename) do
	path = Path.join(File.cwd!(), filename)
	Logger.debug(".env file path: #{path}")

Most of these are conditional, i.e. they won't log if the variable is set or file exists.
But this last one ... I have to agree with @vans163 is sloppy. 🤦‍♂️

Todo

• Re-introduce Logs into the project but they should:
  • Be OFF by default i.e. not noisy! [they can be enabled on :dev or :test]
  • Respect the Logging level of the "parent" (e.g. Phoenix) App.

Side Quest:

What features do we need?

We need to:

• check for the presence of an environment variable e.g: `Getenv.
• give the developer a helpful/friendly error/warning message when the variable is not set

Add Dependabot to Update Dependencies

Just spotted another Elixir project that doesn't have auto-dependency updates.
Not really a problem in the case of this repo where we have no actual depenencies only :dev and :test ...

envar/mix.exs

Lines 33 to 44 in 5d5291d

	defp deps do
	[
	# track test coverage: https://github.com/parroty/excoveralls
	{:excoveralls, "~> 0.13.2", only: [:test, :dev]},
	# Create Documentation Hex.docs: https://hex.pm/packages/ex_doc
	{:ex_doc, "~> 0.22.6", only: :dev},
	# Keep Code Tidy: https://github.com/rrrene/credo
	{:credo, "~> 1.6.2", only: [:dev, :test], runtime: false},
	]
	end

But just for completeness and to delegate updating to 🤖 ...

Todo:

• Create a file with the following path: .github/dependabot.yml

With the following contents:

version: 2
updates:
- package-ecosystem: mix
  directory: "/"
  schedule:
    interval: daily
    time: "07:00"
    timezone: Europe/London

Docs: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot

see: https://github.com/dwyl/fields/tree/main/.github

Set an Environment Variable

• Create Envar.set/2 using System.put_env(key, value)

Publish Package

Publish envar package to Hex.pm: https://hex.pm/packages/envar