📎 Webclip
Configuring your Elixir Application at Runtime with Vapor
The text describes issues Elixir teams face when relying on compile‑time config/*.exs files, especially as applications and deployment setups grow more complex. It contrasts compile‑time and runtime configuration, summarizes recent Elixir features that clarify this boundary, and introduces the vapor library as a practical way to move configuration to runtime using environment variables. The example walks through loading .env files, converting environment variables into application configuration on startup, and then refining that using Vapor’s providers.
Reading notes#
- Configuration has been a recurring pain point in the Elixir community, and recent work aims to make it easier to solve, particularly by improving runtime configuration.
- Many teams using
config/*.exsencounter problems as apps and deployment strategies scale, even though some smaller or simpler applications work fine with this approach. - A common confusion arises when
System.get_env/1is used inconfig.exs; it is evaluated at compile time, so missing env vars in the build environment produce incorrect production configuration. - The desired behavior is to read environment variables at runtime in the environment where the release actually runs, rather than when it is compiled.
- Because
System.get_env/1in config is evaluated at compile time, a release built for staging cannot safely be reused in production; separate builds are needed for each environment. - Reusing the same tested build artifact across staging and production is safer, since it reduces configuration and build differences between environments.
- Libraries that rely on
Application.get_env/3for behavior effectively support only a single configuration instance, which makes it hard to use multiple instances (for example, an API client with multiple API keys) in a concurrent runtime. - Historically, integrating secret management tools like Vault or AWS Secrets Manager was awkward and relied on conventions such as
REPLACE_OS_VARSindistilleryor{:system, "ENV_VAR"}markers to signal runtime evaluation. - Elixir 1.9 introduced
mix releaseand modules likeConfig,Config.Provider, andConfig.Reader, along with Elixir 1.10’sApplication.compile_env/3to clearly denote compile‑time configuration. - There are plans to deprecate using
Application.get_env/3at compile time, which would further reduce accidental misuse of configuration intended for runtime. - New libraries, including
vapor, help make the division between runtime and compile‑time configuration more explicit and easier to handle. - A broader shift is encouraged where libraries and apps move away from heavy use of application environment and instead accept configuration as function arguments.
- The
init/2callbacks in Ecto andPhoenix.Endpointare cited as good examples of enabling runtime configuration for repos and endpoints. - To start with
vapor, the library is added as a dependency inmix.exsusing{:vapor, "~> 0.8.0"}. vaporcan be integrated in the application’sstart/2callback by callingVapor.load!([%Vapor.Provider.Dotenv{}])before starting children in the supervision tree.- The Dotenv provider allows
vaporto read.envor.env.testfiles and populate the system environment at runtime, and does nothing if these files are absent. - The example shows an initial compile‑time configuration for
VaporExample.Endpointsettinghttp: [port: 4000]inconfig/config.exs. - This endpoint port setting is moved to runtime by deleting the
httpentry inconfig.exs, addingPORT=4000to.env, and adding aload_system_env/0function in the application module. - The first version of
load_system_env/0reads thePORTenv var withSystem.get_env/1, raises if it is missing, converts the value to an integer, and then callsApplication.put_env/3for the endpoint’shttpconfiguration. - This approach ensures that whether the app is started via
mixor as a release, and indev,test, orprod, the port configuration behaves consistently. - Failing fast on missing configuration prevents the application from starting in a subtly broken state, enforcing correctness early in the boot process.
- The author proposes a guiding rule that any configuration that can be set at runtime should be set at runtime.
- The initial manual
load_system_env/0contains boilerplate for reading and converting env vars, whichvaporcan simplify through its provider API. - A refined
load_system_env/0version uses%Vapor.Provider.Env{bindings: [ {:port, "PORT", map: &String.to_integer/1} ]}andVapor.Provider.load!/1to map env vars to a config struct. - This
vapor‑based approach still converts string values like"4000"into integers and surfaces missing variables as errors, but centralizes logic in a consistent configuration API. - Once the basic runtime setup with
vaporis in place, developers can gradually migrate other compile‑time configurations to runtime. - After maximizing runtime configurability, teams can further reduce reliance on the application environment itself by using callbacks like
init/2and passing configuration as arguments where possible. - Adopting this runtime‑oriented configuration style is presented as a way to keep Elixir applications correctly configured in the long term and to give teams a clearer, more uniform configuration workflow.
