Phoenix onboarding

Today I spent another short session trying to install and take the first steps with an open source tool that seems interesting. My choice for this morning was Phoenix.


This framework interests me for a few reasons, but mainly because I’m dipping my toe into some realtime-ish web development stuff, and I am hesitating on “Sticking to Rails” even though Rails 5 seems to have some tools built in for this sort of work. So to me, as a total outsider, Phoenix means some capabilities for building realtime apps, backed by the Erlang VM, with Elixir as a handy bridge to make things feel on the surface level to be a bit more Ruby-like.

I am an intermediate level Rails developer and I have a basic understanding of Erlang, but haven’t used Elixir much at all before. Still, this seems like an interesting place to play, and I need everything up and running before I can do that, right?

The first page I landed on was Phoenix’s Overview guide, which has what looks to be a conference talk front and center. I bet that’s interesting, but the first 90 seconds of it do not immediately show me some sort of demonstration–and I’m literally so impatient that this causes me to close the video. (Real talk: I initially only watched for about ten seconds before giving up, and only checked the first 90s after writing this post! I am the worst.)

The thing is, I already am here on this page knowing I want to try Phoenix. I know next to nothing about Phoenix, but I’m open to the possibility that it might be useful to me, and so I just want to know how to get the bits and bobs in the right place so that I can start playing. Maybe others want the lecture first, but I don’t.

I scan the site’s sidebar and find the Up and Running guide. Yes! That’s what I’m looking for, I think. It tells me to go read the Phoenix Installation Guide first, so I head over there.

That guide tells me to first get Elixir set up by following the Elixir Installation Guide and I do that. I already have Homebrew set up on OS X, so installing Elixir only requires running two commands. (Actually, that’s a small lie, I had to unlink an old version of Elixir which I forgot was installed, but that was easy and Homebrew told me how to do it.)

I close the Elixir Install Guide tab in my browser and am back on the Phoenix install guide. It tells me I need to install the Hex package manager and gives me the command I need to run to do that, which works without issues.

Then it warns me about the possibility that Erlang might not be installed but reassures me that most package managers do install it (Homebrew is one that does, I think? I already had Erlang installed either way.)

Then it gives me a command to run to install Phoenix, and tells me what to do if for some reason that command doesn’t work. But the first command works without issues, so I ignore the “what if it doesn’t work” instructions.

Then the guide tells me about Plug, Cowbow, and Ecto, which are default packages used by Phoenix which if I do nothing will be automatically set up so that I don’t need to worry about them. Not sure why I needed this info? But alright, that’s fine.

Then there’s something about Node.js being an optional dependency, because it’s a dependency of a dependency of an optional dependency ( No problem, I already have Node set up, although it seems like this is usually the underlying reason of why I have Node set up. I’ve never built an actual Node application myself. This is fine except that I have no clue whether I’ll one day update Node (or not update it) and it’ll break a bunch of different tools in different ways.

I close the installation guide and get back to the Up and Running Guide: It gives me two ways to create a new project and I run the shorter command. I only realize after scrolling that it tells me that’s what I should have done, along w. some other notes about what to expect.

One of the things that I skipped over was an explanation about how if when the setup asks you to install the dependencies for the application and you say “no” then it will lead to a broken application and you should have either installed them manually or used a flag before you ran that command if you didn’t want that to happen. I said “yes” so fortunately I don’t have that problem, and I do have even though I still have no clue what that is.

I could take time to read all of this stuff, and if I were seriously evaluating Phoenix for a first project, I should take time to read it. Long before I shipped Phoenix into production I would read it. But right now I just want to play around, and so as long as by computer doesn’t break as a result of installing this stuff, I do not care about what dependencies are being used and why, I just want the shortest path to application building!

The project skeleton is generated and within its root directory I run a command that’s supposed to set up the Postgresql database that will back the application. I already have Postgresql set up for use with Rails, so this wasn’t a step I needed to worry about when installing dependencies.

When I run the database creation command, it asks me if it’s OK to install Rebar. I don’t know what Rebar is, but sure, why not? And I don’t know what will happen if I say no.

Rebar installs successfully, but then the command fails with a fatal error, because my Postgresql setup does not have a postgres role configured. It was at this point where I was about to search for a StackOverflow post due to muscle memory, but on a closer skim, the guide actually does mention this scenario, and helpfully links to a guide that explains how to resolve that problem.

At first the in-page anchor doesn’t work so I’m just looking at the top of a massive document. I click it again and somehow it brings me to roughly the right place.

The advice boils down to “Create a postgres role” and has some basic documentation on how to do that. This requires me to remember how to manually run psql with my current setup, because I almost never need to do that. But then after I do that, running the following line on the psql console works just fine:


Confession time: I have no clue what I just did. I think that the postgres user is probably meant for system-level access for PostgresSQL or something like that… my setup is done differently through whatever tutorial I followed for “Postgres Rails OS X”. In production work, either someone else on the team is responsible for the production/staging servers or I use services like Heroku who hide all these details, so I’m a first-class “muddle through it in development” sort of person and have no idea about the inner workings of these low-level dependencies.

I probably should know more about them, so I start to feel guilty about that at this moment in the setup process, but then I remind myself that I only install new stuff very rarely and so it’s not a big source of friction for me, and never something that negatively impacts my customers.

Anyway, where was I? Literally, what page was I supposed to be on? Ah yes, I close my most recent tab and now I’m back to the Phoenix Up and Running Guide.

It tells me how to fire up a server, and I do that. It works without issues, and hey, I see the welcome page!


I love this page because it has some useful links on it, and I also love it because I’ve just slogged for 20 mins through miscellaneous “run this and then that and if that doesn’t work try this…” sort of stuff, and so this is my first small win.

But this is Phoenix’s “Hello World” to me, not my “Hello World” to Phoenix. A subtle but crucial difference, but one that I care a lot about. So I follow the link at the bottom of the Up and Running guide and end up on the Adding Pages guide which is supposed to be the next step in the process of building stuff with Phoenix.

There is great information in this guide, but probably too much detail, and probably not quite in the right order. I skate past a couple pages of “This is what our folder structure looks like” to find the A New Route section, which is where the real instructions begin.

I am familiar with Rails, and because Phoenix is vaguely Rails like, I am not surprised that I need to touch four files in order to get a Hello World page to render–a route, a controller, a view, and a template. I am overall even slightly curious at this point, because now that I’m digging into these files I can start to see how they are similar/different to things I already know. But for the most part, I’m still thinking “just tell me where I need to put this stuff so I can see what happens!”–and many pages of documentation hurt more than they help. Explanations are very useful to me, but only after I have an end-to-end example running.

I get my four files in place and amazingly, did not mess up any of my copy-pasting. I even stopped for a minute to install the language-elixir package in Atom… because without syntax highlighting it’s hard for me to spot syntax errors. This all goes smoothly, and soon enough I’m looking at a Hello page coming from code I at least pasted into the right places… a sign I have at least the very basic beginnings of a working environment.

I go back through the second example in this guide which adds a parameterized route that lets me put Hello, Gregory onto the page by visiting /hello/Gregory — I only need to touch three files this time to make that happen, and I’m basically convinced that this workflow is very close to Rails and can not stress about it anymore.

So what happens next? Unfortunately, nothing. There’s no link at the end of this guide page to the next step, and the sidebar is just a bunch of different framework features. There’s no demonstration application I can find on the site, and it seems like the best bet for finding one might be to buy a book.

I’m sure if I dig deeper, I’ll muddle through. But I haven’t done any CRUD stuff yet, and so I’m not even sure that I can read and write to the database I set up. I got as far as Hello World, and then was sent off into the forest to figure things out for myself.

The difficult admission here is that when it comes to complicated open source projects, the Phoenix documentation and setup process were in my view, above average in their quality and consideration for the kinds of problems developers might run into. But they’re also representative of the incredibly low bar we’ve set for onboarding in open source tools, and also the shit soup that we build our libraries and frameworks on top of.

We can and must do better than this! The real challenge is to figure out how to do it in a way that’s reasonable–particularly in projects that are built by volunteers.

So… that’s something I’ll keep thinking on. But I think I’ll also keep doing these onboarding teardowns so that we can understand the problems better, which may eventually lead to better solutions.

%d bloggers like this: