Up and Running

The aim of this first guide is to get a Phoenix application up and running as quickly as possible.

Before we begin, please take a minute to read the Installation Guide. By installing any necessary
dependencies beforehand, we'll be able to get our application up and running smoothly.

At this point, we should have Elixir, Erlang, Hex, and the Phoenix archive installed. We should
also have PostgreSQL and node.js installed to build a default application.

Ok, we're ready to go!

We can run mix phx.new from any directory in order to bootstrap our Phoenix application.
Phoenix will accept either an absolute or relative path for the directory of our new project.
Assuming that the name of our application is hello, let's run the following command:

$ mix phx.new hello

A note about webpack before we begin: Phoenix will use webpack for asset management by
default. Webpack's dependencies are installed via the node package manager, not mix. Phoenix
will prompt us to install them at the end of the mix phx.new task. If we say "no" at that point,
and if we don't install those dependencies later with npm install, our application will raise
errors when we try to start it, and our assets may not load properly. If we don't want to use
webpack at all, we can simply pass --no-webpack to mix phx.new.

A note about Ecto: Ecto allows our Phoenix application to communicate with a data store, such
as PostgreSQL, MySQL, and others. If our application will not require this component we can
skip this dependency by passing the --no-ecto flag to mix phx.new. This flag may also be
combined with --no-webpack to create a skeleton application.

To learn more about mix phx.new you can read the Mix Tasks Guide.

mix phx.new hello

* creating hello/config/config.exs
* creating hello/config/dev.exs
* creating hello/config/prod.exs
...
* creating hello/assets/static/images/phoenix.png
* creating hello/assets/static/favicon.ico

Fetch and install dependencies? [Yn]

Phoenix generates the directory structure and all the files we will need for our application. When
it's done, it will ask us if we want it to install our dependencies for us. Let's say yes to that.

Fetch and install dependencies? [Yn] Y

* running mix deps.get
* running mix deps.compile
* running cd assets && npm install && node node_modules/webpack/bin/webpack.js
--mode development

We are almost there! The following steps are missing:

$ cd hello

Then configure your database in config/dev.exs and run:

$ mix ecto.create

Start your Phoenix app with:

$ mix phx.server

You can also run your app inside IEx (Interactive Elixir) as:

$ iex -S mix phx.server

Once our dependencies are installed, the task will prompt us to change into our project directory
and start our application.

Phoenix assumes that our PostgreSQL database will have a postgres user account with the
correct permissions and a password of "postgres". If that isn't the case, please see the Mix Tasks
Guide to learn more about the mix ecto.create task.

Ok, let's give it a try. First, we'll cd into the hello/ directory we've just created:

$ cd hello

Now we'll create our database:

$ mix ecto.create
Compiling 13 files (.ex)
Generated hello app
The database for Hello.Repo has been created

Note: if this is the first time you are running this command, Phoenix may also ask to install
Rebar. Go ahead with the installation as Rebar is used to build Erlang packages.

And finally, we'll start the Phoenix server:

$ mix phx.server
[info] Running HelloWeb.Endpoint with cowboy 2.5.0 at http://localhost:4000

Webpack is watching the files…

...
If we choose not to have Phoenix install our dependencies when we generate a new application,
the mix phx.new task will prompt us to take the necessary steps when we do want to install
them.

Fetch and install dependencies? [Yn] n

We are almost there! The following steps are missing:

$ cd hello
$ mix deps.get
$ cd assets && npm install && node node_modules/webpack/bin/webpack.js
--mode development

Then configure your database in config/dev.exs and run:

$ mix ecto.create

Start your Phoenix app with:

$ mix phx.server

You can also run your app inside IEx (Interactive Elixir) as:

$ iex -S mix phx.server

By default Phoenix accepts requests on port 4000. If we point our favorite web browser at
http://localhost:4000, we should see the Phoenix Framework welcome page.
Using MySQL
Phoenix applications are configured to use PostgreSQL by default, but what if we want to use
MySQL instead? In this guide, we’ll walk through changing that default whether we are about to
create a new application, or whether we have an existing one configured for PostgreSQL.

If we are about to create a new application, configuring our application to use MySQL is easy.
We can simply pass the --database mysql flag to phoenix.new and everything will be
configured correctly.

$ mix phoenix.new hello_phoenix --database mysql

This will set up all the correct dependencies and configuration for us automatically. Once we
install those dependencies with mix deps.get, we’ll be ready to begin working with Ecto in our
application.

If we have an existing application, all we need to do is switch adapters and make some small
configuration changes.

To switch adapters, we need to remove the Postgrex dependency and add a new one for Mariaex
instead.

Let’s open up our mix.exs file and do that now.

defmodule HelloPhoenix.Mixfile do
use Mix.Project

. . .
# Specifies your project dependencies
#
# Type `mix help deps` for examples and options
defp deps do
[{:phoenix, "~> 1.2.0"},
{:phoenix_ecto, "~> 3.0"},
{:mariaex, "~> 0.6.1", override: true},
{:phoenix_html, "~> 2.3"},
{:phoenix_live_reload, "~> 1.0", only: :dev},
{:cowboy, "~> 1.0"}]
end
end

We also need to remove the :postgrex app from our list of applications and substitute the
:mariaex app instead. Let’s do that in mix.exs as well.

defmodule HelloPhoenix.Mixfile do
use Mix.Project

. . .
def application do
 [mod: {MysqlTester, []},
applications: [:phoenix, :cowboy, :logger,
:phoenix_ecto, :mariaex]]
end
. . .

Next, we need to configure our new adapter. Let’s open up our config/dev.exs file and do that.

config :hello_phoenix, HelloPhoenix.Repo,

adapter: Ecto.Adapters.MySQL,
username: "root",
password: "",
database: "hello_phoenix_dev"

If we have an existing configuration block for our HelloPhoenix.Repo, we can simply change
the values to match our new ones. The most important thing is to make sure we are using the
MySQL adapter adapter: Ecto.Adapters.MySQL,.

We also need to configure the correct values in the config/test.exs and

config/prod.secret.exs files as well.

Now all we need to do is fetch our new dependency, and we’ll be ready to go.

$ mix do deps.get, compile

With our new adapter installed and configured, we’re ready to create our database.

$ mix ecto.create
The database for HelloPhoenix.repo has been created.

We’re also ready to run any migrations, or do anything else with Ecto that we might choose.

$ mix ecto.migrate
[info] == Running HelloPhoenix.Repo.Migrations.CreateUser.change/0 forward
[info] create table users
[info] == Migrated in 0.2s
mix phx.new View Source
Creates a new Phoenix project.

It expects the path of the project as an argument.

mix phx.new PATH [--module MODULE] [--app APP]

A project at the given PATH will be created. The application name and module name will be
retrieved from the path, unless --module or --app is given.

Options

 --umbrella - generate an umbrella project, with one application for your domain, and a
second application for the web interface.

 --app - the name of the OTP application

 --module - the name of the base module in the generated skeleton

 --database - specify the database adapter for Ecto. One of:

o postgres (https://github.com/elixir-ecto/postgrex)
o mysql (https://github.com/elixir-ecto/myxql)

Please check the driver docs, between parentheses, for more information and
requirements. Defaults to "postgres".

 --no-webpack - do not generate webpack files for static asset building. When choosing
this option, you will need to manually handle JavaScript dependencies if building HTML
apps

 --no-ecto - do not generate Ecto files.

 --no-html - do not generate HTML views.

 --binary-id - use binary_id as primary key type in Ecto schemas

 --verbose - use verbose output

When passing the --no-ecto flag, Phoenix generators such as phx.gen.html, phx.gen.json
and phx.gen.context may no longer work as expected as they generate context files that rely
on Ecto for the database access. In those cases, you can pass the --no-context flag to generate
most of the HTML and JSON files but skip the context, allowing you to fill in the blanks as
desired.
Similarly, if --no-html is given, the files generated by phx.gen.html will no longer work, as
important HTML components will be missing.

Examples
mix phx.new hello_world

Is equivalent to:

mix phx.new hello_world --module HelloWorld

Or without the HTML and JS bits (useful for APIs):

mix phx.new ~/Workspace/hello_world --no-html --no-webpack

As an umbrella:

mix phx.new hello --umbrella

Would generate the following directory structure and modules:

hello_umbrella/ Hello.Umbrella
apps/
hello/ Hello
hello_web/ HelloWeb

You can read more about umbrella projects using the official Elixir guide

To print the Phoenix installer version, pass -v or --version, for example:

mix phx.new -v

Link to this section Summary

Functions
generate(base_path, generator, path, opts)

run(argv)

A task needs to implement run which receives a list of command line args.