deployment-gotchas

Deployment Gotchas

Not a deployment guide — these are the 7 things that break every first Phoenix deploy. Every rule maps to a real production incident pattern.

RULES — Follow these with no exceptions

1. Use runtime.exs for secrets and URLs — config.exs/prod.exs are compiled into the release and cannot read env vars at boot
2. Run migrations via release commands (bin/migrate) — mix is not available in production releases
3. Set PHX_HOST and PHX_SERVER=true — without these, URL generation breaks and the server won't start
4. Run mix assets.deploy before building the release — forgetting this means no CSS/JS in production
5. Never hardcode secrets — use System.fetch_env!/1 in runtime.exs (the ! crashes on boot if missing, which is what you want)
6. Split health checks into liveness and readiness — liveness returns 200 without touching the DB; only readiness queries the database
7. Use config :logger, level: :info in production — :debug logs query parameters including user data

---

1. runtime.exs vs config.exs

The incident: App deploys fine but uses the wrong database URL. DATABASE_URL was set correctly in the environment, but the release ignores it.

Why: config.exs and prod.exs are evaluated at compile time and baked into the release. runtime.exs is evaluated at boot time and can read environment variables.

Bad:

# config/prod.exs — compiled into release, cannot read env vars at boot
config :my_app, MyApp.Repo,
  # Evaluated at BUILD time — captures the build machine's env, not the
  # runtime env. Silently wrong in a release; use runtime.exs instead.
  url: System.get_env("DATABASE_URL")

Good:

# config/runtime.exs — evaluated at boot, reads env vars correctly
if config_env() == :prod do
  database_url = System.fetch_env!("DATABASE_URL")

  config :my_app, MyApp.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
end