I recently got a pull request merged into the popular Phoenix Framework, and I did it without writing any Elixir code. I didn't write any documentation either. What I did was help improve the build process.

In this post, I'd like to share the improvements I made to their build process. These improvements are not Phoenix Framework-specific and they might change the way you approach continuous integration.

But first, some background.

What is the Phoenix Framework?

Phoenix is a web framework with some very interesting properties. With Phoenix, you can build rich interactive web applications without writing client-side code.

You can do this using a feature called LiveView which sends real-time updates from the server to update the client browser's HTML.

We can create a page that shows the latest tweets on a topic, in real-time, quite easily.

Here is an example:

defmodule TimelineLive do
  use Phoenix.LiveView

  def render(assigns) do
    render("timeline.html", assigns)
  end

  def mount(_, socket) do
    Twitter.subscribe("elixirphoenix")
    {:ok, assign(socket, :tweets, [])}
  end

  def handle_info({:new, tweet}, socket) do
    {:noreply,
     update(socket, :tweets, fn tweets ->
       Enum.take([tweet | tweets], 10)
     end)}
  end
end

Real-Time Twitter Results with No Javascript Written

The framework is written in the programming language Elixir

It was created by José Valim. It looks a lot like Ruby but has very different semantics. Elixir runs on the Erlang VM, and it powers projects like Discord and is used at companies like Heroku.

How to Reproduce the Builds

The Phoenix Framework uses GitHub Actions for their build pipeline. Like many great projects, they have a suite of unit tests that they need to run on every user contribution.

This isn't where their testing efforts stop though. They also have a suite of integration tests. Phoenix uses an ORM to talk to various databases and the integration tests ensure that no changes break the integration with any of the 3 supported databases.

This is a common pattern. Having a large number of unit tests that are easy to run and well as a handful of slower but more comprehensive integration tests is a great way to prevent bugs from being introduced into the project.

The Phoenix Framework takes this even further, though, as they also need to support several versions of the Elixir language and a handful of versions of Open Telecom Platform (OTP).

This is starting to sound complex. We have to test each change with all combinations of the following:

• Databases (Postgres, MySQL MSSQL)
• Elixir (Current and Previous Version)
• OTP (Current and Previous Version)

It's relatively easy to set this up in GitHub Actions, but how would you run these tests locally?

Installing all these would be a lot to ask, so contributors tend to rely on GitHubActions to test these combinations. However, if everyone has to rely on pushing things to GitHub it see if the tests pass then development gets slower.

How do we fix this?

How to Unify the Test Runs

This is where I got involved. I work at Earthly Technologies as an open-source developer advocate. We have a pretty cool open-source build tool, and although I occasionally contribute directly to the project my job is to be the contact point between the community using the tool and the team working on it.

I had heard about this reproducibility problem the Phoenix team was having. I thought I could help write a build script that could be used both in GitHub Actions and for a local development workflow. So I set to work on a PR.

Running The Tests Locally

What I ended up creating, slightly simplified, is this:

setup:
   ARG ELIXIR=1.10.4
   ARG OTP=23.0.3
   # Pull a Docker Image to Run Build Inside Of
   FROM hexpm/elixir:$ELIXIR-erlang-$OTP-alpine-3.12.0
   ...

integration-test:
    FROM +setup
    COPY . .
    # Pull In Dependencies
    RUN mix deps.get 
    # Start Up Service Dependencies
    WITH DOCKER --compose docker-compose.yml 
        # Run Tests
        RUN mix test --include database 
    # Stop Service Dependencies
    END

This is an Earthfile. Its made up of several targets, like setup and integration-test. The targets can have dependencies between them. You can use the command-line tool earthly to run any target and each is run in a Docker container. Containerization is going allow us to run the build wherever we choose.

This example runs the integration-test inside of a the hexpm/elixir Docker container with the specified version of Elixir and OTP installed.

Before running the tests with mix test --include database, we use Docker compose to start up all the needed dependencies:

 WITH DOCKER --compose docker-compose.yml
        RUN mix test --include database
 END

The Docker compose file looks like this:

version: '3'
services:
  postgres:
    image: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: postgres
  mysql:
    image: mysql
    ports:
      - "3306:3306"
    environment:
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
  mssql:
    image: mcr.microsoft.com/mssql/server:2019-latest
    environment:
      ACCEPT_EULA: Y
      SA_PASSWORD: some!Password
    ports:
      - "1433:1433"

These are the databases we need for testing Phoenix.

Now we can run the integration tests at the command line like so:

>  earthly -P +integration-test

And if we want to test a different version of Elixir, we can specify the version as build arguments:

 > earthly -P --build-arg ELIXIR=1.11.0 --build-arg OTP=23.1.1 +integration-test

There are other ways to accomplish this. A combination of a makefile and dockerfiles would have worked as well. The key is to get the build logic out of a GHA specific format and into something that be run can anywhere.

How to Run it in GitHub Actions

To use this same process inside GitHub Actions, the only thing we need to do is adjust our GitHub Actions yaml to use Earthly for the build pipeline and we are all set.

  integration-test-elixir:
    runs-on: ubuntu-latest
    env:
      FORCE_COLOR: 1

    strategy:
      fail-fast: false
      matrix:
        include:
          - elixir: 1.11.1
            otp: 21.3.8.18
          - elixir: 1.11.1
            otp: 23.1.1
    steps:
      - uses: actions/checkout@v2
      - name: Download released earth
        run: "sudo /bin/sh -c 'wget https://github.com/earthly/earthly/releases/download/v0.4.1/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly'"
      - name: Execute tests
        run: earthly -P --build-arg ELIXIR=${{ matrix.elixir }}  --build-arg OTP=${{ matrix.otp }} +integration-test

There we go, we are now able to run our build pipeline locally, without any complex environment setup. We can also run the same build process on our developer machine without needing to install anything except Earthly. This makes it easier for new contributors to approach the project.

The End Result

Eventually, with help from the Phoenix Team, I got this change approved and the Phoenix project now has an easy way to test and iterate on their build pipeline locally. And I didn't even write any Elixir code! You can find more details in the PR.

Thank you for reading this article. If you'd like to learn more about Earthly, you can find out a lot here. And if you'd like my help on your open source project's build, let me know.

In this post, we’ll discuss how to build a boilerplate Phoenix web app with user authentication and an admin panel, along with image upload in Elixir.

TodoMVC has become a de facto tool to compare various JavaScript-based MV* frameworks. Along the same lines, I feel that a blog application can be a tiebreaker in choosing a new backend or API framework.

So let’s get started and build one in Phoenix. We’ll follow the default setup, that is Phoenix hooked up with Ecto running on PostgreSQL.

Here are the final screens to give you an idea of what the app will look like at the end.

The landing page will show all the published blogs in a card layout. A card can be clicked to view that particular post.

We will have a dashboard that will show the statistics in brief. Access to this page requires admin user login.

There will be a separate section that has an overview of all the posts. Here you can publish / modify / delete posts.

This is the post editor layout featuring a markdown editor along with a file picker for the featured image.

Note: The full working code is hosted on GitHub. There are numerous files in the project which cannot be shared in a single blog. So I have explained the specific ones which I assume are critical.

Let’s keep the project’s name as CMS for now. So we’ll start with creating a new project with mix phx.new cms. Run mix deps.get to install dependencies.

Generate a migration file for users and posts, respectively.

# User migration file

mix phx.gen.schema Auth.User users name:string email:string password_hash:string is_admin:boolean

# Posts migration file

mix phx.gen.schema Content.Post posts title:string body:text published:boolean cover:string user_id:integer slug:string

Two tables have to be created in the database which represent users and posts. I’ve kept it rather simple, keeping only the required fields and expanding when the need arises.

Subsequently, we can define changesets and additional methods in the user and post schema as well.

user.ex

post.ex

@derive {Phoenix.Param, key: :slug}

Since we want the posts to have a readable and SEO friendly URL structure, we inform route helpers to reference slug instead of id in the URL namespace.

The routes are described here:

Resources which are specific to the admin section are clubbed together and assigned a pipeline which forces authentication.

Meanwhile, global routes are treated with passive authentication. User details are fetched if a session is present but the pages are still accessible. Login and home pages belong here.

Executing mix phx.routes gives me this output:

The view is divided into three logical sections:

1. Navigation bar
2. Sidebar
3. Main Content

While the navigation bar is always visible, the sidebar appears only if an admin user is logged in. Browsing content will be inside the admin context. The links in the sidebar will grow as and when the app evolves.

The Admin.Post controller follows the typical CRUD architecture and includes an action to toggle the published state of a given post.

A lot of controls reside in the index page of admin’s post section. Here, posts can be deleted, published and modified.

templates/admin/post/index.html.eex

To keep the template uncluttered, we can define convenience view helpers like formatting time etc. separately.

views/admin/post_view.ex

Arc along with arc_ecto provides out of the box file upload capabilities. Since a post features a cover image, we have to define an arc configuration in our app.

Each post in our blog requires two versions of cover images — original which is visible inside specific post view and a thumb version with a smaller footprint to populate the cards. For now, let’s go with 250x250 resolution for the thumb version.

Coming back to the app’s landing page, it will house the cards for all the published posts. And each post will be accessible through the slug formed.

controllers/page_controller.ex

This project explores Phoenix — how a Phoenix app is structured and how to dismantle a Phoenix-based project. I hope you’ve learned something and enjoyed it!

The full working app is on Github : https://github.com/ramansah/cms. Feel free to clone ? and do clap if you find this blog useful ?

Authentication is always a tricky subject. People tend to use so many types of authentication in their apps. Authentication using an email address and a password with an option confirm password field is the most common. But every time you see a registration form, you feel bored thinking that you’ll have to type in so much just to register! What’s the fun in that!

So, for this app, I’ll be doing authentication using your Google account. It’s pretty straightforward. You just need to click on a button, give the app the necessary permissions to access you basic Google profile and you’re set! Cool, isn’t it?

We will be using Ueberauth, Ueberauth Google and Guardian for authenticating our user. Ueberauth and Ueberauth Google will help authenticate the user with their Google credentials. Guardian will help us in generating a JSON Web Token for logged in users. That token is necessary and needs to be in the header of each request for any route which needs authentication.

Guardian will check for that token in the requests’ header and if the token is valid, the authenticated routes will be available to the user. I’ll explain these things in details.

If you hadn’t already installed Phoenix and its necessary dependencies, you can head over to the Phoenix Guides to install and get up and running.

To get started add the dependencies to our mix.exs.

defp deps do  [   ...      {:ueberauth, "~> 0.4"},   {:ueberauth_google, "~> 0.2"},   {:ja_serializer, "~> 0.11.2"},   {:guardian, "~> 0.14.2"}]end

After this, run mix deps.get to fetch the dependencies.

You also need to add ueberauth and ueberauth_google to our application in mix.exs.

def application do  [mod: {SocialAppApi, []},   applications: [   ...      :ueberauth, :ueberauth_google]]end

Now, you will need to add your ueberauth, ueberauth_google and guardian configuration to your config/config.exs file.

# Ueberauth Config for oauthconfig :ueberauth, Ueberauth,  base_path: "/api/v1/auth",  providers: [    google: { Ueberauth.Strategy.Google, [] },    identity: { Ueberauth.Strategy.Identity, [        callback_methods: ["POST"],        uid_field: :username,        nickname_field: :username,      ] },  ]

# Ueberauth Strategy Config for Google oauthconfig :ueberauth, Ueberauth.Strategy.Google.OAuth,  client_id: System.get_env("GOOGLE_CLIENT_ID"),  client_secret: System.get_env("GOOGLE_CLIENT_SECRET"),  redirect_uri: System.get_env("GOOGLE_REDIRECT_URI")

# Guardian configurationconfig :guardian, Guardian,  allowed_algos: ["HS512"], # optional  verify_module: Guardian.JWT,  # optional  issuer: "SocialAppApi",  ttl: { 30, :days },  allowed_drift: 2000,  verify_issuer: true, # optional  secret_key: System.get_env("GUARDIAN_SECRET") || "rFtDNsugNi8jNJLOfvcN4jVyS/V7Sh+9pBtc/J30W8h4MYTcbiLYf/8CEVfdgU6/",  serializer: SocialAppApi.GuardianSerializer

As you can see here, I’ve used System.get_env() . This is a way to store credentials in your app which you don’t want to be a part of your codebase. You can create a .env file and store all of these credentials like:

export DB_NAME_PROD="social_app_api_db"export DB_PASSWORD_PROD="password"export DB_USERNAME_PROD="password"

After this, you need to do source .env and then, you can use them in your app.

Now, we’ll need to do a bunch of stuff with our controllers which will let the user to sign up or sign in.

First, create a new file web/controllers/auth_controller.ex.

defmodule SocialAppApi.AuthController do  use SocialAppApi.Web, :controller  plug Ueberauth

  alias SocialAppApi.User  alias MyApp.UserQuery

  plug :scrub_params, "user" when action in [:sign_in_user]

  def request(_params) do  end

  def delete(conn, _params) do    # Sign out the user    conn    |> put_status(200)    |> Guardian.Plug.sign_out(conn)  end

  def callback(%{assigns: %{ueberauth_failure: _fails}} = conn, _params) do    # This callback is called when the user denies the app to get the data from the oauth provider    conn    |> put_status(401)    |> render(SocialAppApi.ErrorView, "401.json-api")  end

  def callback(%{assigns: %{ueberauth_auth: auth}} = conn, _params) do    case AuthUser.basic_info(auth) do      {:ok, user} ->        sign_in_user(conn, %{"user" => user})    end

  case AuthUser.basic_info(auth) do      {:ok, user} ->        conn        |> render(SocialAppApi.UserView, "show.json-api", %{data: user})      {:error} ->        conn        |> put_status(401)        |> render(SocialAppApi.ErrorView, "401.json-api")    end  end

  def sign_in_user(conn, %{"user" => user}) do    try do      # Attempt to retrieve exactly one user from the DB, whose      # email matches the one provided with the login request      user = User      |> where(email: ^user.email)      |> Repo.one!

      cond do        true ->          # Successful login          # Encode a JWT          { :ok, jwt, _ } = Guardian.encode_and_sign(user, :token)

          auth_conn = Guardian.Plug.api_sign_in(conn, user)          jwt = Guardian.Plug.current_token(auth_conn)          {:ok, claims} = Guardian.Plug.claims(auth_conn)

          auth_conn          |> put_resp_header("authorization", "Bearer #{jwt}")          |> json(%{access_token: jwt}) # Return token to the client

        false ->          # Unsuccessful login          conn          |> put_status(401)          |> render(SocialAppApi.ErrorView, "401.json-api")      end    rescue      e ->        IO.inspect e # Print error to the console for debugging

        # Successful registration        sign_up_user(conn, %{"user" => user})    end  end

  def sign_up_user(conn, %{"user" => user}) do    changeset = User.changeset %User{}, %{email: user.email,      avatar: user.avatar,      first_name: user.first_name,      last_name: user.last_name,      auth_provider: "google"}

    case Repo.insert changeset do      {:ok, user} ->        # Encode a JWT        { :ok, jwt, _ } = Guardian.encode_and_sign(user, :token)

        conn        |> put_resp_header("authorization", "Bearer #{jwt}")        |> json(%{access_token: jwt}) # Return token to the client      {:error, changeset} ->        conn        |> put_status(422)        |> render(SocialAppApi.ErrorView, "422.json-api")    end  end

  def unauthenticated(conn, params) do    conn    |> put_status(401)    |> render(SocialAppApi.ErrorView, "401.json-api")  end

  def unauthorized(conn, params) do    conn    |> put_status(403)    |> render(SocialAppApi.ErrorView, "403.json-api")  end

  def already_authenticated(conn, params) do    conn    |> put_status(200)    |> render(SocialAppApi.ErrorView, "200.json-api")  end

  def no_resource(conn, params) do    conn    |> put_status(404)    |> render(SocialAppApi.ErrorView, "404.json-api")  endend

Here sign_in_user will sign the user in and throw an access_token as the response. The sign_up_user will sign the user up using their Google credentials and then throw an access_token as the response. This token is essential in the way that Guardian will check for this access_token in all the requests’ header. It will check if the user is currently in session or not. If yes, all the authenticated routes will be available to the user. Otherwise, he will receive a 401 response for the authenticated routes.

Let’s add some routes to our app. Our router.ex file looks like this:

defmodule SocialAppApi.Router do  use SocialAppApi.Web, :router

  pipeline :api do    plug :accepts, ["json", "json-api"]    plug JaSerializer.Deserializer  end

  pipeline :api_auth do    plug :accepts, ["json", "json-api"]    plug Guardian.Plug.VerifyHeader, realm: "Bearer"    plug Guardian.Plug.LoadResource    plug JaSerializer.Deserializer  end

  scope "/api/v1", SocialAppApi do    pipe_through :api_auth

  resources "/users", UserController, except: [:new, :edit]    get "/user/current", UserController, :current, as: :current_user    delete "/logout", AuthController, :delete  end

  scope "/api/v1/auth", SocialAppApi do    pipe_through :api

    get "/:provider", AuthController, :request    get "/:provider/callback", AuthController, :callback    post "/:provider/callback", AuthController, :callback  endend

Here, pipeline api_auth is the one which is authenticated. The pipeline api isn’t. So, we can visit get “/:provider”, AuthController, :request without signing in.

Create another file called web/models/auth_user.ex with the following code:

defmodule AuthUser do  alias Ueberauth.Auth

  def basic_info(%Auth{} = auth) do    {:ok,      %{        avatar: auth.info.image,        email: auth.info.email,        first_name: auth.info.first_name,        last_name: auth.info.last_name      }    }  endend

You will also need to create a User model.

mix phoenix.gen.json User users email:string auth_provider:string first_name:string last_name:string avatar:string

This will generate your necessary model and migration.

Your model will look something like this:

defmodule SocialAppApi.User do  use SocialAppApi.Web, :model

  schema "users" do    field :email, :string    field :auth_provider, :string    field :first_name, :string    field :last_name, :string    field :avatar, :string

    timestamps()  end

  def changeset(struct, params \\ %{}) do    struct    |> cast(params, [:email, :auth_provider, :first_name, :last_name, :avatar])    |> validate_required([:email, :auth_provider, :first_name, :last_name, :avatar])    |> unique_constraint(:email)  endend

Your migration file will look something like this:

defmodule SocialAppApi.Repo.Migrations.CreateUser do  use Ecto.Migration

  def change do    create table(:users) do      add :email, :string      add :auth_provider, :string      add :first_name, :string      add :last_name, :string      add :avatar, :string

      timestamps()    end

    # Unique email address constraint, via DB index    create index(:users, [:email], unique: true)  endend

Now, run the migration.

mix ecto.migrate

Also, create a UserController for our user model. That will contain the following code:

defmodule SocialAppApi.UserController do  use SocialAppApi.Web, :controller

  alias SocialAppApi.User

  plug Guardian.Plug.EnsureAuthenticated, handler:     SocialAppApi.AuthController

  def index(conn, _params) do    users = Repo.all(User)    render(conn, "index.json-api", data: users)  end

  def current(conn, _) do    user = conn    |> Guardian.Plug.current_resource

    conn    |> render(SocialAppApi.UserView, "show.json-api", data: user)  endend

This is useful in case you want to check if the authenticated routes work or not after all your hard work.

Create two more views at web/views/error_view.ex with the following code:

defmodule SocialAppApi.ErrorView do  use SocialAppApi.Web, :view  use JaSerializer.PhoenixView

  def render("401.json-api", _assigns) do    %{title: "Unauthorized", code: 401}    |> JaSerializer.ErrorSerializer.format  end

  def render("403.json-api", _assigns) do    %{title: "Forbidden", code: 403}    |> JaSerializer.ErrorSerializer.format  end

  def render("404.json-api", _assigns) do    %{title: "Page not found", code: 404}    |> JaSerializer.ErrorSerializer.format  end

  def render("422.json-api", _assigns) do    %{title: "Unprocessable entity", code: 422}    |> JaSerializer.ErrorSerializer.format  end

  def render("500.json-api", _assigns) do    %{title: "Internal Server Error", code: 500}    |> JaSerializer.ErrorSerializer.format  end

  # In case no render clause matches or no  # template is found, let's render it as 500  def template_not_found(_template, assigns) do    render "500.json-api", assigns  endend

Also, create another view web/views/user_view.ex with the following code:

defmodule SocialAppApi.UserView do  use SocialAppApi.Web, :view  use JaSerializer.PhoenixView

  attributes [:avatar, :email, :first_name, :last_name, :auth_provider]end

And, you are all set. Fire up your server:

mix phoenix.server

Now, go to http://localhost:4000/api/v1/auth/google and you will be redirected to Google’s login page. Once you give the app the necessary permissions, you will get an access_token in the response:

{  access_token: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJVc2VyOjIiLCJleHAiOjE0ODk4NjM4MzUsImlhdCI6MTQ4NzI3MTgzNSwiaXNzIjoiU29jaWFsQXBwQXBpIiwianRpIjoiODU0NzJhODAtN2Q4Ny00MjM0LWIxNmUtODgyMTBmYWZkZDJmIiwicGVtIjp7fSwic3ViIjoiVXNlcjoyIiwidHlwIjoiYWNjZXNzIn0.L2LjpsyJAjF1r99hR11WVGcQ"}

Now, you can install the Modheader extension for Chrome and any other extension through which you can set response headers. Add Authorization as a Request Header and the access_token with Bearer <access_token>.

Modheader

Go to http://localhost:4000/api/v1/users and you will be able to see an array of users you’ve already sign up with. You can also go to http://localhost:4000/api/v1/user/current to see the current user in the session.

If you remove that value from Modheader and go to http://localhost:4000/api/v1/users, you will get the following response:

{  jsonapi: {    version: "1.0"  },  errors: [{    title: "Unauthorized",    code: 401  }]}

As I’ve mentioned earlier, you need to send the access_token received to view the authenticated routes. Now, you know how to do API authentication in Elixir. You can compare your code with my code on Github.

If you have some feedback, let me know in the comments below.

One of the most difficult aspects of starting a programming project is coming up with a project idea in the first place. No inspiration means no programming!

Luckily, I recently discovered a project idea with a nice pacing to it: a basic Node.js and Express.js application using Spotify’s API and Twilio.

If you’d like to follow along with the JavaScript version, check out this video. If you want to build it in Gradle and Spark, here’s Twilio’s original post.

For this article, we’ll build this app using Elixir and Phoenix. Let’s get started.

Here’s the general flow of the app:

• You text the title of a song to a Twilio number
• Twilio makes an HTTP POST to a preconfigured url with some infomation including the song title and information about the requester
• The application searches the Spotify API for the song, and parses out a preview url
• The application dispatches a message to the Twilio API. This includes the number to call and a url to fetch some TwiML(Twilio Markup Language)
• Twilio fetches the TwiML from our application, calls the recipient, and plays them the song preview.

I’ve been through a majority of the curriculum at Free Code Camp. I helped design and build a large part of the core systems behind Free Code Camp, so I’m very comfortable with JavaScript. Following along with the presentation was easy, and I was quick to recreate it. The questions was, could I do it with a language and framework I didn’t have solid experience with?

If you’d like to know what the finished product looks like, text the title of a song to +1 (334) 721–2652. Don’t worry, we won’t save your phone number or song. Request all the ABBA you want!

NOTE: I’ve loaded some funds into this to keep it going a while. I’m hosting it on Heroku so it may take a moment to wake up and respond. If it doesn’t respond at all, the funds I added have been exhausted.

Here’s a short video of me interacting with my app using Google Voice.

I wanted to challenged myself and play with a language that I’ve been smitten with since hearing about it. Elixir is a gorgeous language with Ruby inspired syntax. Elixir runs on the BEAM (Erlang VM), and is interoperable with Erlang. Yes, Erlang of WhatsApp fame. I love the idea of being able to tap into that kind of power and reliability. I also love functional programming.

On top of Elixir, I’m also a fan of the Phoenix web framework. It’s easy to get started with, and easy to get things done in. The error messages are excellent and tend to tell you exactly how to fix them. Trust me on this, I’ve seen enough of them.

The first task is is to generate a new Phoenix application. I called mine Philter, so I typed:

mix phoenix.new philter --no-ecto --no-brunch

With this, we’re creating a new phoenix application called Philter, with no database layer and no JavaScript build system. We won’t be using any JavaScript in this project!

Follow the on-screen instructions to finish setting up the application. We’re now ready to work through our list of tasks.

Twilio

Twilio makes it pretty easy to setup an account. As an aside, their documentation and console are top notch. It’s one of my favorite web services to use.

Sign up for Twilio here. If you want to follow along with this tutorial, you’ll have to add some funds. $5 would be more than enough to give you days of playing around. If you decide to follow along, buy a phone number and keep your browser tab open.

Ngrok

The next service you’ll want to use is ngrok. This handy little service tunnels into a specified port on your computer and gives you a public url to use. The service is completely free, but I signed up for the $5/mo plan so I could have a reserved subdomain. It’s the little things, I tell ya.

Open a new terminal tab and install ngrok via npm. Then use ngrok to specify that you’d like to create an http tunnel to port 4000 on your computer.

# is a comment for your information# ~ represents your terminal prompt~ npm i -g ngrok

...~ ngrok http 4000ngrok by @inconshreveable                           (Ctrl+C to quit)

Tunnel Status             onlineVersion                   2.1.1Region                    United States (us)Web Interface             http://127.0.0.1:4040Forwarding                http://someurl.ngrok.io -> localhost:4000Forwarding                https://someurl.ngrok.io -> localhost:4000

Now switch back to your original terminal tab and start your phoenix app.

~ iex -S mix phoenix.server      # <or>~ mix phoenix.server

The first option starts the server in an interactive shell that will let you interact with it. Regardless of your method of starting it, you’ll see it log out that it’s listening on your local machine on port 4000.

Now open a new browser tab and visit localhost:4000 to confirm it’s working. Then, paste in the url from the Forwarding http line in the ngrok terminal that I bolded above. You’ll see your app there too. Magic!

Go back to the tab you have your Twilio console open in, and find your phone number. Click on it, and you should see some configuration information. Under the messaging section, “When a message comes in”, enter the url from ngrok followed by “api/sms”. Ensure the HTTP method is set to POST. For reference, while building this application mine was set to http://tkb.ngrok.com/api/sms

While we have the Twilio console open, get your ACCOUNT SID and AUTH TOKEN credentials. You can find them by clicking on your account name in the top right hand corner of the window and looking at the “API Credentials” section. Create two environmental variables, TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN. I use an extension of the preferences panel on my Mac called EnvPane. You can also search google and get a ton of results if you need help setting yours.

With all that information at hand, we’re nearly ready to tie it all together. We have one last thing to configure. We’re going to use ExTwilio, a library to help our phoenix application talk to Twilio.

Open config/config.exs and add the following above the final import statement:

config :ex_twilio,  account_sid: System.get_env(“TWILIO_ACCOUNT_SID”),  auth_token: System.get_env(“TWILIO_AUTH_TOKEN”)

Here’s where we’re telling our application to read in these two environmental variables so we can send messages and make phone calls through Twilio’s API.

In your favorite editor of choice (mine is Spacemacs), open your Phoenix application directory. Let’s get down to business.

Open web/router.ex and get rid of any scope stuff you see. Replace it with:

scope “/”, Philter do  pipe_through :browser

  post “/twiml”, TwimlController, :indexend

scope “/api”, Philter do  pipe_through :api

  post “/sms”, SmsController, :indexend

Replace any mention of Philter with whatever name you gave your application.

The above code did a few things. We have a created a route that will match POSTs to http://yourngrokurl/twiml and route to TwimlController’s index function. We also did the same for the http://yourngrokurl/api/sms route, passing off to SmsController’s index function. Learn more about routing in Phoenix by checking out the excellent documentation.

Now create two files in the web/controllers/ directory, _smscontroller.ex and _twimlcontroller.ex. Make your _smscontroller.ex look like:

defmodule Philter.SmsController do  use Philter.Web, :controller

  alias Philter.Sms

  def index(conn, %{"Body" => song, "From" => from, "To" => to}) do

    Task.start_link(fn -> search_spotify(song, %{from: from, to:     to}) end)    send_resp(conn, 200, “”)   end

  defp search_spotify(song, twilio_data) do    Philter.Spotify.search(song, twilio_data)  endend

To those Elixirists reading this, please keep in mind I’m still very much learning. With that disclaimer out of the way, on to a brief explanation.

Twilio will post the phone number of the requester in a From field, our Twilio number in the To field, and the body of their text in the Body field. We’re fishing those out, then spawning a task to search the Spotify API.

Spawning a task executes some long running function in a super lightweight BEAM process. If something happens to the process, like it crashes or catches on fire or is stricken by cosmic rays, our application will happily continue accepting connections and prevent moments of developer panic.

A full discussion of Tasks and OTP in general is far beyond the scope of this article. Please refer to the Elixir links in this post if you’d like to learn more about this amazing beast.

Now refer to the GitHub repository for this project. The files you’ll want to copy are lib/philter/spotify.ex and the entire lib/philter/spotify/ directory. Ensure you go through the files, changing any mention of Philter to your own application name. In spotify.ex, on line 55, replace “tkb” in the url to whatever your ngrok url is.

Now make your _twimlcontroller.ex look like the following:

defmodule Philter.TwimlController do  use Philter.Web, :controller

  alias Philter.Twiml

  def index(conn, %{"song" => song) do    render(conn, “index.html”, song: song)  endend

All we’re doing here is fishing the song out and and then passing it along as a variable to our template.

Open the app.html.eex in the web/templates/ directory and delete everything except for:

 <%= render @view_module, @view_template, assigns %>

We don’t need any of that other markup!

Next, create a file under the web/views/ directory called _twimlview.ex. We could put helper functions in here, but we don’t need any so it’s just going to live as a shell file. The contents should be:

defmodule Philter.TwimlView do  use Philter.Web, :viewend

Now create a new directory under web/templates/ called twiml/ and inside of it create a file called index.html.eex. The contents are straightforward:

 <?xml version=”1.0" encoding=”UTF-8" ?> <Response>   <Say>Please enjoy the clip!&lt;/Say>   <Play><%= @song %></Play>   <Say>I hope you enjoyed your song clip</Say> </Response>

This is the response we’ll send to Twilio when they ask us for TwiML in response to our API interaction within the task I barely touched on. Feel free to play around, and reference the great TwiML documentation.

With a restart of Phoenix, you should be able to text your Twilio phone number and get a phone call with the song preview!

Dénouement

I had a lot of fun implementing this little application with Elixir. Much like when I was learning JavaScript, I had to wrap my head around how to go about doing things, using functions correctly (even finding the correct functions to use!), and ensuring the application logic was correct.

There were many furrowed brows and a lot of documentation and online tutorials were referenced as I dove deeper into Elixir. I was very pleasantly surprised at how little Phoenix specific code was needed though. It’s a great framework in my opinion.

In the end, the final product made the temporary frustrations worth it. Getting reactions out of my wife and friends like “That’s so cool!” or “You made that?” are definitely worth the effort. It also helped cement patterns and notions I had about how things worked more clearly. Maybe after I get out of the military, I will indeed be able to transition into a career in programming.

I have to give a shout out to Twilio. They’ve made an excellent project. Every interaction I needed to perform was well documented, and their management console itself made it easy to find what I needed and configure actions on that end.

If you are interested in learning more about Elixir and Phoenix, I’d highly recommend Programming Elixir, Elixir In Action, and Programming Phoenix. I have all 3 and they are excellent! The online documentation is well above par, and more and more tutorials and articles are popping up. In general, the Elixir community is one of the best out there.

We are definitely excited to add Elixir to our backend languages at FreeCodeCamp.

Learning to code is hard. I’d highly recommend signing up for FreeCodeCamp and following along the very structured and self-paced learning track we’ve established. Thousands upon thousands of people are finding success, and we have a massive community of helpful people - beginners to professionals - in our Gitter room.

Remember, don’t let something as ephemeral as frustration at a task today keep you from achieving your goals tomorrow. Happy coding!