DEV Community

Cover image for Learn Elixir and Phoenix by building a read-it-later service: Project Setup
Oliver Andrich
Oliver Andrich

Posted on • Updated on • Originally published at

Learn Elixir and Phoenix by building a read-it-later service: Project Setup

I work as CTO at a company that primarily uses Java and Python on the server and JavaScript on the client - besides some more exotic languages and the usual toolchain for app development. While using a rather conservative technology stack by day, I enjoy to look into different toolchains and technologies in my spare time. So, I decided to look into Elixir and Phoenix this time as part of my #100daysofcode and #learninpublic challenge.

I plan to do this as a series of post on covering all steps from setting up the project to deploying it on some PaaS platform. This won't be a detailed course of Elixir or Phoenix, but I will add links to more detailed references here and there.

Hopefully, in the end I fell in love with Elixir and Phoenix. The pure functional environment and scalability of the Elixir platform is intriguing.

The Project

I prefer to learn new technologies by implementing a real project or a product. It is fine for me to work through an excellent book like Programming Phoenix 1.4 and implement the learning project. But I only develop a deeper understanding when I have implemented my own ideas or something from a well-understood problem domain.

I love read-it-later services! Unfortunately, I have not found one that fully meets my requirements. And I tried all of them. So, this seems to be a good learning project. It also covers many nice aspects:

  • adding a decent CSS framework (Tailwind CSS)
  • User Management and Registration
  • Authentication
  • interacting with a Database
  • Building a web frontend
  • An API to connect a browser plugin to
  • An admin interface
  • ...

But we start as usual by installing the required tools and configuring the development project.

Set up the development environment

For macOS and Windows it is fairly easy to set up your development environment using a tool like Homebrew or Chocolatey. Just open a shell and run some simple commands. To follow this series you need Elixir, Phoenix, PostgreSQL and Node.js. (Node.js is required for the asset pipeline.)

On macOS:

brew install elixir postgresql node
Enter fullscreen mode Exit fullscreen mode

On Windows:

choco install elixir postgresql12 nodejs
Enter fullscreen mode Exit fullscreen mode

Next up, we use mix the Elixir build tool to install the hex package manager and the current version of the phoenix framework.

mix local.hex
mix archive.install hex phx_new 1.5.3
Enter fullscreen mode Exit fullscreen mode

Now everything is in place to start our shiny new project.

If you need more background on this. Check out the installation document on the Phoenix website.

Create the initial project

Phoenix works just like all the other modern full-featured web frameworks when creating a new project - you run a command to scaffold your project. In case of Phoenix it is a mix task.

mix read_it_later
Enter fullscreen mode Exit fullscreen mode

The output of the command looks like that.

* creating read_it_later/config/config.exs
* creating read_it_later/config/dev.exs
* creating read_it_later/config/prod.exs
* creating read_it_later/config/prod.secret.exs
* creating read_it_later/config/test.exs
* creating read_it_later/lib/read_it_later/application.ex
* creating read_it_later/lib/read_it_later.ex

Fetch and install dependencies? [Yn] y
* running mix deps.get
* running cd assets && npm install && node node_modules/webpack/bin/webpack.js --mode development
* running mix deps.compile

We are almost there! The following steps are missing:

    $ cd read_it_later

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
Enter fullscreen mode Exit fullscreen mode

Configure the database connection

If your mind works a bit like mine does, you read over the sentence "Then configure your database in config/dev.exs and..." and just typed mix phx.server into your console window.

BAMM! You made the same mistake I always make and get some ugly database errors. Do yourself a favour, open the file config/dev.exs and change the settings for the development database connection.

# Configure your database
config :read_it_later, ReadItLater.Repo,
  username: "oa",
  password: "",
  database: "read_it_later_dev",
  hostname: "localhost",
  show_sensitive_data_on_connection_error: true,
  pool_size: 10
Enter fullscreen mode Exit fullscreen mode

In case of macOS and Homebrew the default user for PostgreSQL is your shell user with an empty password. In my case, it is oa.

Now you can run the following two commands. The first will create the development database with the name read_it_later_dev. The second will start the development server.

mix ecto.create
mix phx.server
Enter fullscreen mode Exit fullscreen mode

Now, start your browser and open the URL http://localhost:4000/. You should see the default start page of a fresh Phoenix project.

Alt Text

Anatomy of a Phoenix project

Let's finish up this post with a short overview of the directory structure and some important files.

├── _build
│   └── ...
├── assets
│   ├── css
│   ├── js
│   ├── ...
│   ├── static
│   └── webpack.config.js
├── config
│   ├── config.exs
│   ├── dev.exs
│   ├── prod.exs
│   ├── prod.secret.exs
│   └── test.exs
├── deps
│   └── ...
├── lib
│   ├── read_it_later
│   ├── read_it_later.ex
│   ├── read_it_later_web
│   └── read_it_later_web.ex
├── mix.exs
├── mix.lock
├── priv
│   ├── gettext
│   ├── repo
│   └── static
└── test
    └── ...
Enter fullscreen mode Exit fullscreen mode
  • build is the output directory of the Elixir compiler.
  • assets contains the typical static files (CSS, JS, images). But it also contains a preconfigured modern asset pipeline based on webpack.
  • In the folder config you find the overall config file config.exs and the customizations for the environments' development (dev), production (prod) and testing (test).
  • deps is the location where the project dependencies are stored. If you come from JavaScript, you can compare it to the infamous node_modules folder. But it will never grow as big as its JavaScript cousin.
  • lib' is the folder where your source code is located. Normally, the mix task that creates a new project creates two packages -read_it_laterandread_it_later_web`. At first this might be confusing, but if you have understood a little about the project structure of a Phoenix project, it makes perfect sense.
  • mix.exs is the project configuration file. Again, if you come from JavaScript it is comparable to the package.json file.
  • priv contains contain non-source-code files of your project. Database migrations, i18n files, etc.
  • Well, the content of test should be obvious.

The code

I share the code to this project on github. Every post gets its own tag on the repository, so you can easily switch to the code of a given post.

GitHub logo oliverandrich / learn-elixir-and-phoenix-project

This is the demo project from by blogpost series on

Summary and next steps

So far, this was pretty straight forward but also somewhat boring. You now know what I am up to, and we created an initial project. I shared some insights I had during this early stage of my learning project.

Next up, I will add Tailwind CSS to the project because I love this utility-first CSS library. It is a great basis for a design system.

I hope you enjoyed this first post and will follow me on my journey learning Elixir and Phoenix.

Credits: Cover image by Katie Drazdauskaite on Unsplash

Discussion (1)

pbjoiner profile image
Paul B. Joiner

I inherited an Elixir/Phoenix project with no knowledge of Erlang, Elixir, or backend programming. Your tutorials helped me to dive in and (I hope) fix a broken and wildly outdated project. Thank you, thank you, and thank you with a side of thank you sauce.