How to Get Started with Elixir Phoenix

Treat this article as a quick-ref to getting started with Elixir Phoenix. The Phoenix docs and guides are excellent as the Phoenix community treats documentation contributions as first-class contributions to the framework. Also the Phoenix books such as Programming Phoenix 1.4 are a great way to learn the framework. I recommend reading the guides at least.


Prerequisites

This article assumes you have some dependencies installed on your machine. Here is a useful list of references for getting each dependency installed.

Database: PostgreSQL

Most Phoenix projects as well as this series of articles will use the PostgreSQL database. Downloads and instructions for installing PostgreSQL are found on the download page of the PostgreSQL project.

JavaScript Runtime: Node.js

Phoenix uses the Node.js JavaScript runtime.  Downloads and instructions for installing Node.js are found on the project’s downloads page.

Language and Virtual Machine: Elixir and Erlang

Phoenix is written in Elixir. Elixir compiles to the Erlang virtual machine. Installation instructions for Elixir (which will usually also install Erlang) are found on the Installing Elixir page of the Elixir language project. Follow the installation instructions using the installer for your environment. 

Finally, Phoenix!

Install Phoenix like so:

$ mix archive.install hex phx_new 1.4.10

Checkpoint

Before continuing forward, confirm that Phoenix and its dependencies are installed.  

You should be able run the version flag (-v) like so:

$ mix phx.new -v

This should return the version of Phoenix currently installed.

Phoenix v1.4.10

If you get any errors, exceptions or other messages, take a look through the Phoenix installation guide for additional instructions and troubleshooting tips. If you still have any questions or issues, feel free to reach out to me!


Creating the Phoenix Application!

Earlier, we used “mix” to install Phoenix as well as to create our Phoenix project. mix is Elixir’s command-line build tool which is used for almost all steps of creating and managing an Elixir project. We will use mix extensively throughout this series, including now. Let’s create our Phoenix app! 

As this application will eventually demonstrate how to accomplish a wide variety of tasks in Phoenix and become our demo app, let’s name it Demo.

Create with phx.new

1. Create and/or move to a directory in your environment where you would like the project source code to live. It can be anywhere, for me it’s:

MacBookPro:~ smeade$ cd Projects
/Users/smeade/Projects

2. From that directory, enter the phx.new mix command.

$ mix phx.new demo
* creating demo/config/config.exs
….
Fetch and install dependencies? [Yn] Y

3. When prompted to Fetch and install dependencies? [Yn], answer Y.

4. After the mix task completes, follow the next steps:

$ cd demo

5. Configure your database in config/dev.exs and run:

$ mix ecto.create

Note: If you run ecto.create you might see this error:

** (Mix) The database for Demo.Repo couldn’t be created: ERROR 42501 (insufficient_privilege) permission denied to create database

When a phoenix project is first generated, the database configuration (in the file dev.exs) looks like this:

# found in dev.exs
# Configure your database
config :demo, Demo.Repo,
  username: "postgres",
  password: "postgres",
  database: "demo_dev",
  hostname: "localhost",
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

If you do not have a PostgreSQL user of postgres with password postgres, you will need to change this configuration to credentials that are available on your local database environment. For example, I have a user “phx” with password “phx”, so I update my dev.exs file like so:

# found in dev.exs
# Configure your database
config :demo, Demo.Repo,
  username: "phx",
  password: "phx",
  database: "demo_dev",
  hostname: "localhost",
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

6. Start your Phoenix app with:

$ mix phx.server

Open the App!

Now you should be able to open your browser to http://localhost:4000 and see the “Welcome to Phoenix!” screen!

I’m happy to help out if anything in this article is unclear or not working for you. Reach out to me at https://twitter.com/smeade

Thanks for reading. In a following article, we’ll create our first “Hello World!” page.