Getting Started with Phoenix

For those interested in writing applications in Phoenix, a web framework written in the functional programming language Elixir, there are currently lots of resources on the Web for getting started on your local machine. Although we can directly install Elixir via Homebrew, I want to share a short step-by-step guide here for using a version manager that will help handle various dependencies and versioning in the future. While helping some of my coworkers set up Phoenix projects, I’ve also noticed some common roadblocks that developers run into when installing the framework’s various dependencies, which I will note at the end of the post.

What you’ll need

  • Laptop with MacOS operating system
  • Homebrew

Steps to install Elixir

  1. Install Asdf First.

Asdf is an extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more, and we like to use Asdf, because we can rely on one version manager to manage multiple languages (instead of separate version managers like RVM for Ruby, NVM for Node, EXM for Elixir, etc.). You can follow the Asdf readme or paste the following into your terminal:

git clone ~/.asdf --branch v0.6.0

Make sure you can run asdf in your terminal before continuing. If you cannot, the Asdf readme has some good tips depending on your OS and shell.

2. Next, install Erlang before installing Elixir.

Since the only prerequisite for Elixir is Erlang (Elixir is a functional programming language built on top of the Erlang Virtual Machine), we should first install Erlang on our local machine. However, before running asdf install, don’t forget to run the following:

brew install autoconf

This ensures that we have the build tools we need before downloading Erlang!

Each version of Elixir supports different versions of Erlang, so make sure that you have the right Erlang version for the Elixir version you’re about to install. For reference, this is the compatibility table between Elixir and Erlang/OTP.

For our example here, we will install Erlang/OTP 20.1.

A. Install the Erlang Asdf plugin: asdf plugin-add erlang

B. Install a specific version of Erlang (this usually takes a while ~5 mins): asdf install erlang 20.1

C. Set the package global version: asdf global erlang 20.1

3. Finally, install Elixir!

For our example here, we will install Elixir 1.6.4.

A. Install the Elixir Asdf plugin:asdf plugin-add elixir

B. Install a specific version of Erlang: asdf install elixir 1.6.4

C. Set the package global version: asdf global elixir 1.6.4

Issues with Postgres During Setup

At this point, you should be able to run mix phx new [name of project] and follow the list of suggested commands to start developing your Phoenix application.

** If you run into any issues with Postgres when starting the Phoenix server, below are some troubleshooting tips:

  • Postgres Version Compatibility issue:
waiting for server to start….2018–09–28 15:37:14.675 EDT [39217] FATAL: database files are incompatible with server
2018–09–28 15:37:14.675 EDT [39217] DETAIL: The data directory was initialized by PostgreSQL version 9.6, which is not compatible with this version 10.5.
stopped waiting
pg_ctl: could not start server
Examine the log output.

If you see something like this when starting mix phx.server this means that you currently have a PostgresSQL version that is not supported by Postgrex, the PostgreSQL driver for Elixir. According to the documentation for Postgrex, it currently supports PostgreSQL 8.4, 9.0–9.6, and 10.0.

You will need to unlink the current PostgresSQL version, brew install a PostgresSQL version (such as 9.6) that is supported by Postgrex and link to the version that is supported:

brew unlink postgresql

brew install postgresql@9.6

brew link postgresql@9.6

  • Postgres Role Does Not Exist
** (Mix) The database for ProjectName.Repo couldn't be created: FATAL 28000 (invalid_authorization_specification): role "postgres" does not exist

If you are seeing this error message when running mix phx.server, you may be missing the default PostgresSQL role, postgres. This can be fixed with the following command:

First, connect to the PostgresSQL database server using the psql client:

psql postgres

Next, we can go ahead and create a role postgres and add createdb permission to the role:

postgres=# create role postgres with password 'postgres';
postgres=# alter role postgres with login;
postgres=# alter role postgres createdb;
postgres=# \q

That’s it. We should be able to get started with writing our first Phoenix app!