Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Installing Phoenix and Creating a Project

Install Elixir, Erlang, PostgreSQL and the Phoenix generator, then create and run your first Phoenix app with mix phx.new and see the welcome page.

Getting a Phoenix app running takes four steps: install Elixir and Erlang, install the Phoenix project generator, create the project and start the server. This lesson walks through each one, explains the generator's options and shows how to fix the most common first-run problems.

You will need a terminal and basic familiarity with Mix projects, since a Phoenix app is a Mix project with extra structure.

None of the commands below can run on this site; they run on your own computer. The JavaScript TryIts at the end of the lesson are stand-ins that model what the generator and the dev server do.

What you need installed

Tool Why
Erlang/OTP The runtime (the BEAM)
Elixir The language; Phoenix needs a recent version, see the Phoenix guides for the current minimum
PostgreSQL The default database (SQLite and MySQL are supported too)
Node.js Not required: Phoenix downloads standalone Tailwind and esbuild binaries itself

The easiest way to install Erlang and Elixir with matching versions is a version manager such as mise or asdf. On macOS you can also use Homebrew; on Windows there is an official installer, and WSL2 gives a Linux-like setup.

Terminal
# with mise
mise use -g erlang@latest elixir@latest

# check
elixir --version

Elixir prints the Erlang/OTP version and its own version. Both must be present.

Install the Phoenix generator

The generator is a Mix archive. Install it once; it works for every new project.

Terminal
mix local.hex          # package manager, once
mix archive.install hex phx_new

Create the app

Terminal
mix phx.new blog

Mix asks whether to fetch and install dependencies. Say yes. The generator creates a blog folder, a Mix project named :blog, a module called Blog for your business logic and BlogWeb for the web layer.

Useful options:

Option Effect
--database sqlite3 Use SQLite instead of PostgreSQL
--no-ecto Skip the database layer
--no-html A JSON-only app: no templates or assets
--no-live Leave LiveView out
--binary-id Use UUIDs as primary keys
--no-mailer Skip Swoosh mail setup
--app my_app --module MyApp Pick names that differ from the folder

For an API you could run mix phx.new blog_api --no-html --no-assets --no-live. In this track we use the default full-stack project.

Set up the database and start the server

Terminal
cd blog
mix ecto.create     # creates the database named blog_dev
mix phx.server      # starts on http://localhost:4000

Open http://localhost:4000. You should see the Phoenix welcome page. To run the server inside an interactive shell, so you can call your code while it runs, use:

Terminal
iex -S mix phx.server

Edit a template or a controller and save: code reloading recompiles the changed file and the browser reloads on its own, because the dev endpoint has live reload enabled.

First-run problems and fixes

  • connection refused from mix ecto.create. PostgreSQL is not running or the credentials differ. Open config/dev.exs and check username, password and hostname under the Blog.Repo config; the defaults are postgres/postgres on localhost.
  • port 4000 already in use. Another process owns it. Stop it, or change http: [port: 4000] in config/dev.exs, or run PORT=4001 mix phx.server (runtime.exs reads PORT in production).
  • Tailwind or esbuild download fails. Run mix assets.setup again with a working connection; the binaries are cached in _build.
  • Compilation warnings about the Elixir version. Update Elixir to a version the Phoenix guides list as supported.

Your first change

Open lib/blog_web/controllers/page_html/home.html.heex and replace the content with your own heading:

HEEX
<h1 class="text-3xl font-bold">My blog</h1>
<p>Built with Phoenix.</p>

Save and the page updates by itself. The route lives in lib/blog_web/router.ex as get "/", PageController, :home.

Model the generator

The generator is nothing magical: it copies a template folder and replaces placeholders such as the app name. This stand-in does the same with a few strings.

JS A mini project generator

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

No output.

Notice how one name, blog_api, becomes the module BlogApi, the web module BlogApiWeb and the database blog_api_dev. That naming convention (snake_case app, CamelCase module) is the same in every Phoenix project.

JS Port checking like phx.server

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

No output.

Phoenix itself does not auto-increment the port; it stops with an error and you choose another. The stand-in only shows why the message matters.

Updating and checking your setup

Once the project works, three commands are worth knowing from day one:

Terminal
mix deps.get      # fetch dependencies after editing mix.exs
mix compile       # compile and show warnings
mix test          # run the generated test suite

The generator creates tests for the welcome page, so mix test should pass immediately. A passing suite on a fresh project is your proof the install is healthy.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command installs the Phoenix project generator?

    The generator is a Mix archive called phx_new, installed once with mix archive.install.
  2. 2. What does mix ecto.create do?

    It creates the database named in your Repo config, such as blog_dev. Tables come from migrations later.
  3. 3. How do you start the server inside an interactive Elixir shell?

    iex -S mix phx.server loads your project into IEx and starts the endpoint, so you can call your code live.
  4. 4. Which option creates a JSON-only app without templates?

    --no-html leaves out HTML templates and assets, which suits API projects.

Summary

  • Install Erlang and Elixir (a version manager helps), PostgreSQL and the phx_new archive.
  • mix phx.new app_name creates the project; mix ecto.create creates the database; mix phx.server runs it on port 4000.
  • Options such as --no-html, --no-ecto and --database sqlite3 shape the generated app.
  • Code reloading and live reload update the browser as you save files.

Next: Project structure and configuration