Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

Project Structure and Configuration

Tour a generated Phoenix project: lib, lib_web, priv, config, assets and tests, and how config.exs, dev.exs, prod.exs and runtime.exs fit together.

A fresh Phoenix project has dozens of files, and the layout can look overwhelming. It follows a few simple rules, though. This lesson maps every top-level folder to its job and explains the configuration files, which are where most beginners get lost.

Knowing the structure makes the rest of this track easier, because each later lesson will say "add a file to this folder" and you will already know why that is the right place.

The two halves of lib/

TEXT
blog/
โ”œโ”€โ”€ assets/            JS, CSS, vendored libraries
โ”œโ”€โ”€ config/            config.exs, dev.exs, test.exs, prod.exs, runtime.exs
โ”œโ”€โ”€ lib/
โ”‚   โ”œโ”€โ”€ blog/          business logic (contexts, schemas, Repo, mailer)
โ”‚   โ”œโ”€โ”€ blog.ex
โ”‚   โ”œโ”€โ”€ blog_web/      the web layer
โ”‚   โ”‚   โ”œโ”€โ”€ components/    layouts, core components
โ”‚   โ”‚   โ”œโ”€โ”€ controllers/   controllers and their HTML/JSON modules
โ”‚   โ”‚   โ”œโ”€โ”€ endpoint.ex
โ”‚   โ”‚   โ”œโ”€โ”€ router.ex
โ”‚   โ”‚   โ””โ”€โ”€ telemetry.ex
โ”‚   โ””โ”€โ”€ blog_web.ex    shared `use BlogWeb, :controller` macros
โ”œโ”€โ”€ priv/
โ”‚   โ”œโ”€โ”€ repo/migrations/   database migrations
โ”‚   โ”œโ”€โ”€ repo/seeds.exs     sample data
โ”‚   โ””โ”€โ”€ static/            compiled assets and files served as-is
โ”œโ”€โ”€ test/
โ””โ”€โ”€ mix.exs

The most important design rule: lib/blog knows nothing about the web, and lib/blog_web talks to it only through function calls. If tomorrow you add a command-line tool or a job runner, it can reuse Blog without any HTTP code. This separation is why Phoenix talks about contexts, which you will meet in associations and contexts.

What lives in each folder

  • lib/blog/application.ex defines the application's supervision tree: the Repo, PubSub, the endpoint and telemetry are all started here. If a process must run for your app to work, it is a child in this file.
  • lib/blog/repo.ex is the database gateway (use Ecto.Repo).
  • lib/blog_web.ex contains the controller, html, live_view and router macros that every web module calls with use BlogWeb, :controller. It is the one place to add shared imports.
  • lib/blog_web/endpoint.ex lists endpoint plugs: static files, session, parsers, the router.
  • priv/ holds files shipped with a release that are not code: migrations, seeds, translations and static assets.
  • test/ mirrors lib/, with test/support for shared case modules and fixtures.

The configuration files

Phoenix uses the standard Elixir config system, loaded in a fixed order.

File When it runs Use it for
config/config.exs At compile time, every environment Settings shared by all environments
config/dev.exs, test.exs, prod.exs Compile time, picked by MIX_ENV Settings that differ per environment
config/runtime.exs At runtime, when the app boots (also in releases) Secrets, URLs and anything read from environment variables

The last row matters most. In production you build one release and deploy it to many places. Database URLs, secret keys and hostnames must therefore be read when the release starts, not baked in during the build. That is the whole purpose of runtime.exs.

ELIXIR
# config/runtime.exs (excerpt)
if config_env() == :prod do
  database_url =
    System.get_env("DATABASE_URL") ||
      raise "environment variable DATABASE_URL is missing"

  config :blog, Blog.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")

  secret_key_base =
    System.get_env("SECRET_KEY_BASE") ||
      raise "environment variable SECRET_KEY_BASE is missing"

  config :blog, BlogWeb.Endpoint,
    url: [host: System.get_env("PHX_HOST") || "example.com", port: 443, scheme: "https"],
    secret_key_base: secret_key_base
end

Raising when a variable is missing is deliberate: the app refuses to boot rather than run misconfigured.

Reading configuration in code

ELIXIR
Application.get_env(:blog, :feature_flags)        # may return nil
Application.fetch_env!(:blog, BlogWeb.Endpoint)   # raises if absent

Prefer fetch_env! for required values so a typo fails loudly. Avoid calling Application.get_env in module attributes: those are evaluated at compile time and will not see runtime.exs values.

Never commit secrets. dev.exs may contain throwaway development values, but production secrets belong in environment variables or a secrets manager, read in runtime.exs.

Config merging, modeled

Elixir loads config.exs, then imports the environment file (import_config "#{config_env()}.exs"), then runtime.exs. Later values win, and keyword lists are deep merged. The stand-in below models that rule.

JS Config files merge in order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that adapter from config.exs survived while url.host was overridden by the runtime file. That is exactly how Elixir config behaves.

A runtime.exs that refuses to start

JS Fail fast on missing variables

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Mix environments

MIX_ENV selects the environment: dev (default for mix phx.server), test (for mix test) and prod (for releases). Code can branch on it, but prefer configuration over Mix.env() checks, since Mix does not exist inside a release.

Terminal
MIX_ENV=prod mix assets.deploy
MIX_ENV=prod mix release

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file should read the production DATABASE_URL?

    runtime.exs runs when the release boots, so it can read environment variables that differ per deployment.
  2. 2. Where does the business logic of a Phoenix app live by default?

    lib/blog holds contexts, schemas and the Repo; lib/blog_web is only the web interface.
  3. 3. What is priv/repo/migrations for?

    Each migration file describes one change to the database schema.
  4. 4. Why is raising an error for a missing SECRET_KEY_BASE a good idea?

    Failing at boot surfaces the problem immediately, before any user request hits a half-configured app.

Summary

  • lib/blog is business logic; lib/blog_web is the web layer, and the two talk through function calls.
  • application.ex defines the supervision tree; blog_web.ex holds shared use macros.
  • config.exs and the per-environment files run at compile time; runtime.exs runs at boot and reads secrets.
  • Config values deep-merge in order, later files winning.

Next: Mix tasks and developer tools