Elixir and Phoenix on MacOS for the First Time: install to first project

Let's install Elixir and Phoenix on MacOS, and create our first web app project.

I looked through 3 separate web pages to figure it out (it was relatively easy), and thought it'd help to gather it into a single page of 10 steps.

What's Elixir?  Elixir is a programming language that superficially looks a little like Ruby, but more importantly is designed to be dynamic, functional, and capable of building concurrent, distributed, low-latency and fault-tolerant systems (perfect for the web!).

It does that by running on the Erlang VM (like a Java VM, not like a VirtualBox VM), and that also gives developers access to Erlang’s ecosystem (this reminds me of how Clojure runs on the JVM, providing access to Java's ecosystem).

What's Phoenix?   Phoenix is an Elixir framework implementing the server side of a web framework for modern web applications.  Like Ruby on Rails or Python's Django, but Phoenix is written in Elixir and derives benefits from that (in addition to whatever other advantages it may have as a framework - we're not comparing frameworks today).

(1) Install Homebrew

To begin, you need Homebrew installed on your MacOS.  Homebrew is a package management system that makes installing lots of developer software much easier on Macs.

Once installed, especially if it's been a while since you've last used Homebrew, make sure to update it (commands after "$" are to be typed in your terminal window):

$ brew update

Do a self diagnostic to make sure it's all okay, carefully read the instructions it provides:

$ brew doctor

(2) Install Elixir

Elixir requires Erlang to be installed.  Fortunately, the Homebrew package will automatically make sure of that.

$ brew install elixir

Once installed, check that Elixir is working (and to see which version):

$ elixir -v

When you install Elixir, it will also install a few other utilities with it, including iex which is the Interactive Elixir, and also mix, a build tool for Elixir.

(3) Install Hex, a package manager for Phoenix

Next, we'll need to install Hex, a package manager for Phoenix, necessary to install a Phoenix project's dependencies.

$ mix local.hex

(4) Install Phoenix

Finally, let's install Phoenix:

$ mix archive.install https://github.com/phoenixframework/archives/raw/master/phoenix_new.ez

(5) Install npm, Node Package Manager

Phoenix, by default, uses brunch.io, which uses the Node Package Manager to get its' dependencies installed.  And npm requires Node.js (version 5 or greater), and is in fact a part of its package.  So installing it is easy from Homebrew:

$ brew install node

Technically, npm (and thus node.js) are optional dependencies for Phoenix, as it can be given options to not use it, but there's no reason not to at this point.

(6) Install PostgreSQL database server

PostgreSQL is the SQL database server (like MariaDB) that Phoenix projects use by default.  It's easily installed with Homebrew:

$ brew install postgresql

Phoenix can be changed to use something else like MySQL by using the database flag when creating a Phoenix project, but there's no reason to at this point (unless you're adamant on using another database server right now).

If you want the database server to be always running, from starting up your Mac, you'll want MacOS's launchd to start it automatically.  Set this up with Homebrew:

$ brew services start postgresql

If you want the database server to be not always running, then run it only when you're developing your Phoenix application with:

$ pg_ctl -D /usr/local/var/postgres start

(7) Set up PostgreSQL user account

Phoenix by default assumes the PostgreSQL database will have an user account with a password of "postgres" (or no password).  You can change this: look for the ecto.create mix task for instructions.  Let's just create a user account with no password for convenience on your development machine for now.

$ createuser -d postgres

(8) Make Phoenix application project

First, navigate (on the terminal with cd) to the directory where you want to create your project. Then enter:

$ mix phoenix.new hi_phoenix

The project name here is "hi_phoenix".  Generally speaking, it must be all lowercase, with the first letter being alphabetic.

(9) Configure your development database

Go into your project folder:

$ cd hi_phoenix

Set up your development database (it can be first configured using the file config/dev.exs if you like) by running:

$ mix ecto.create

(10) Run your Phoenix web application and test it out

Now run the Phoenix server from your project folder to run your Phoenix web app:

$ mix phoenix.server

Or, you could've ran your app inside an iex (Interactive Elixir) session instead like so:

$ iex -S mix phoenix.server

Go to your web browser and navigate to this URL to test the server:


(11) Shut things down and take a break

I know I said 10 steps at the beginning to get it running, but we've got to shut the thing down afterwards right?

Go back to the terminal, and press ctrl-C twice to exit the web server.  It's the same if you were running it in iex.

If you had started running PostgreSQL manually, you may want to stop it manually now:

$ pg_ctl -D /usr/local/var/postgres stop

(12) What's next?

Try running your web app again by taking it from step 10 and on.  Then go add some pages, see Phoenix Framework: Adding Pages.


Phoenix Framework: Installation

Phoenix Framework: Up And Running

Elixir: Installing Elixir


No comments: