Elixir Mix Release: Enforcing Compile‑Time‑Only Configuration Keys

Answer Summary

From OTP 25 onward, mix release supports a persistent: true flag on any configuration entry. This flag causes the key to be baked into sys.config and blocks overrides from System.get_env/2 or Application.put_env/3 at runtime. If you are on an older OTP, there is no built‑in enforcement; you must rely on conventions and runtime checks.

How to Declare a Compile‑Time‑Only Key

1. In config/config.exs (or any config file that runs at compile time), add the persistent: true option to the key:

config :my_app, :secret_key, "super‑secret", persistent: true

2. Re‑compile and build the release with mix release. The generated _build/*/rel/my_app/releases/*/sys.config will contain an entry similar to:

[{my_app, [{secret_key, "super‑secret"}]}]

3. At runtime, the value is read from sys.config and any attempt to override it via an environment variable or Application.put_env/3 will raise an error.

Verification Steps

1. Environment Variable Override Test – Before starting the release, export a different value for the same key:

   export MY_APP_SECRET_KEY=env‑value
   

   Start the release and check the value:

   iex -S mix
   iex> Application.get_env(:my_app, :secret_key)
   "super‑secret"
   

   If the output matches the baked value, persistence is working.
2. Attempt Runtime Override – After the node is running, run:

   Application.put_env(:my_app, :secret_key, "new‑value")
   # => ** (ArgumentError) cannot overwrite persistent key :secret_key
   

   This confirms the key is protected.
3. Inspect sys.config – Open the file in _build/*/rel/my_app/releases/*/sys.config and verify that the key appears only once and is not overridden by any env section.

If You’re on OTP < 25 (No Built‑In Option)

• Keep compile‑time configuration in a dedicated module (e.g., MyApp.Config) and never read System.get_env/2 for those keys.
• Use application environment keys that are only set in config/*.exs and never in config/runtime.exs or via --env flags.
• Document the keys as "compile‑time only" and enforce code reviews to prevent accidental Application.put_env/3 calls.
• At runtime, you can still run the override test above; if the value changes, you know an override occurred.

What to Ask Next?

To tailor the recommendation precisely, could you confirm which OTP version you are targeting for the release?