phoenix

Phoenix Framework Development

This skill activates when working with Phoenix web applications, including setup, development, LiveView, contexts, controllers, and channels.

Current versions: Phoenix 1.8.x (current: 1.8.5), Phoenix LiveView 1.1.x (current: 1.1.27). Requires Elixir 1.14+, Erlang/OTP 25+.

Phoenix Project Structure

Follow Phoenix conventions:

lib/
  my_app/           # Business logic and contexts
    accounts/       # Domain contexts
    repo.ex
  my_app_web/       # Web interface
    controllers/
    live/           # LiveView modules
    components/     # Function components
    router.ex
    endpoint.ex

Runtime configuration

config/runtime.exs runs at every boot (dev, test, prod). Three settings have caused production outages when configured incorrectly:

Phoenix Endpoint :ip bind config

The Endpoint's :ip bind tuple MUST be set at the TOP LEVEL of runtime.exs, env-driven, with a default of {0, 0, 0, 0} (all IPv4 interfaces). Do NOT gate it inside if port = System.get_env("PORT") do ... end, and do NOT override it later in a prod-only block that hardcodes {0,0,0,0,0,0,0,0} (IPv6 wildcard).

CORRECT:

# config/runtime.exs (top level, unconditional)
bind_address =
  case System.get_env("BIND_ADDRESS", "0.0.0.0") do
    "0.0.0.0" -> {0, 0, 0, 0}
    "::" -> {0, 0, 0, 0, 0, 0, 0, 0}
    other -> other |> String.to_charlist() |> :inet.parse_address() |> elem(1)
  end

config :<app>, <App>Web.Endpoint, http: [ip: bind_address, port: ...]

WRONG (gates on PORT):

if port = System.get_env("PORT") do
  config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0}, port: ...]
end
# Without PORT, Phoenix falls back to its default 127.0.0.1 — unreachable.

WRONG (later prod block clobbers env-driven setting):

# Top-level env-driven config OK ...
if config_env() == :prod do
  config :<app>, <App>Web.Endpoint, http: [ip: {0, 0, 0, 0, 0, 0, 0, 0}, ...]
end
# IPv6 wildcard binds *:port IPv6 only — IPv4-only overlay networks (Tailscale on macOS) cannot reach it.