{"id":10948,"date":"2024-07-14T10:34:41","date_gmt":"2024-07-14T10:34:41","guid":{"rendered":"https:\/\/putridparrot.com\/blog\/?p=10948"},"modified":"2025-08-29T19:45:39","modified_gmt":"2025-08-29T19:45:39","slug":"elixir-and-phoenix","status":"publish","type":"post","link":"https:\/\/putridparrot.com\/blog\/elixir-and-phoenix\/","title":{"rendered":"Elixir and Phoenix"},"content":{"rendered":"

Most languages which I start to learn, I’ve found I learn the basics of the language (enough to feel at relative ease with the language) but then want to see it in real world scenarios. One of those is usually a web API or the likes. So today I’m looking at using Elixir along with the Phoenix<\/a> framework.<\/p>\n

Note: I’m new to Elixir and Phoenix, this post is based upon my learnings, trying to get a basic web API\/service working and there may be better ways to achieve this that I’m not aware of yet.<\/em><\/p>\n

Phoenix is a way to (as they say on their site) to “build rich, interactive web applications”. Actually I find it builds too much as by default it will create a website, code for working with a DB (PostgresQL by default) etc. In this post I want to create something more akin to a web API or microservice.<\/p>\n

In this post I want to create a simple API service so instead we’ll use phx.new<\/a> to create a service named my_api and well remove the website\/HTML and ecto (the DB) side of things <\/p>\n

\r\nmix phx.new my_api --no-html --no-ecto --no-mailer\r\n<\/pre>\n
If this fails with a “not found” error, try installing phx using “mix archive.install hex phx_new”<\/em><\/p>\n
If you run the command above you’ll get a new application generated. Just cd my_api<\/em> to allow us to run the service etc. <\/p>\n
If you’d like to see what the default generated application is then run the following<\/p>\n
\r\nmix phx.server\r\n<\/pre>\n
By default this will start a server against localhost:4000. If you open the browser you’ll see a default dashboard\/page which likely says there’s no route for GET \/ and then lists some available routes.<\/p>\n
The \/dev\/dashboard route takes you to a nice LiveDashboard showing information about the Elixir and Phoenix. <\/p>\n
To shutdown the Phoenix server CTRL+C twice within the terminal that you ran it up from.<\/p>\n
For my very simple web service, I do not even what the live dashboard. So if you created that new app. delete your new app folder and then run this minimal code version (unless you’d prefer to keep live dashboard etc.)<\/p>\n
\r\nmix phx.new my_api --no-html --no-ecto --no-mailer --no-dashboard --no-assets --no-gettext\r\n<\/pre>\n
This will then generate a fairly minimal server which is a good starting point for our service. You’ll notice first off that there are now, no routes when you run this via mix phx.server
\n<\/em>. <\/p>\n
Let’s add a controller, this will acts as the controller for our web service, so within the \/lib\/my_api_web\/controllers folder add a new file named math-controller.ex and past the following code into it (obviously change the module name to suite your application name)<\/p>\n
\r\ndefmodule MyApiWeb.MathController do\r\n  #use MyApiWeb, :controller\r\n  use Phoenix.Controller, formats: [:html, :json]\r\n\r\n  def index(conn, _params) do\r\n   json(conn, "{name: Scooby}")\r\n  end\r\nend\r\n<\/pre>\n
We now need to hook up our controller to a route, so go to the router.ex file within the \/lib\/my_api_web\/ folder and alter the scope section to look like this<\/p>\n
\r\nscope "\/", MyApiWeb do\r\n  pipe_through :api\r\n\r\n  resources "\/api", MathController, except: [:new, :edit, :create, :delete, :update, :show]\r\nend\r\n<\/pre>\n
If you run mix phx.server<\/em> you should see a route to \/api, typing http:\/\/localhost:4000\/api will return “{name: Scooby}” as defined in the math-controller index. This is not very math-like so let’s create a couple of functions, one for adding numbers and one for subtracting.<\/p>\n
Remove the resources section (or comment out using #) in the scope then add the following routes<\/p>\n
\r\nget "\/add", MathController, :add\r\nget "\/sub", MathController, :subtract\r\n<\/pre>\n
Go to the math-controler.ex and add the following functions<\/p>\n
\r\ndef add(conn, %{"a" => a, "b" => b}) do\r\n  text(conn, String.to_integer(a) + String.to_integer(b))\r\nend\r\n\r\ndef subtract(conn, %{"a" => a, "b" => b}) do\r\n  text(conn, String.to_integer(a) - String.to_integer(b))\r\nend\r\n<\/pre>\n
Notice we destructuring params to values a and b – we’ll convert those values to integers and use the text<\/em> function to return raw text (previously we expected JSON hence uses the json<\/em> function). Now when you browse the add method, for example http:\/\/localhost:4000\/add?a=10&b=5 or subtract method, for example http:\/\/localhost:4000\/sub?a=10&b=5 you should see raw text returned with answers to the math functions.<\/p>\n
What routes are we exposing<\/strong><\/p>\n
Another useful way of checking the available routes (without running the server) is, as follows<\/p>\n
\r\nmix phx.routes\r\n<\/pre>\n
Config<\/strong><\/p>\n
If you’ve looked around the generated code you’ll notice the config<\/em> folder. <\/p>\n
One thing you might like to do now is change localhost to 0.0.0.0 so edit dev.exs and replace<\/p>\n
\r\nhttp: [ip: {127, 0, 0, 1}, port: 4000],\r\n<\/pre>\n
with<\/p>\n
\r\nhttp: [ip: {0, 0, 0, 0}, port: 4000],\r\n<\/pre>\n
If you do NOT do this and you decide to deploy the dev release to Docker, you’ll find you cannot access your service from outside of Docker (which ofcourse is quite standard). <\/p>\n
Releases<\/strong><\/p>\n
Generating a release will precompile any files that can be compiled and allows us to run the server without the source code (as you’d expect) you will need to tell the compiler what configuration to use, we do that by setting the MIX_ENV like this<\/p>\n
\r\nexport MIX_ENV=prod\r\n<\/pre>\n
(No MIX_ENV environment variable will default dev)<\/p>\n
Then running<\/p>\n
\r\nmix release\r\n<\/pre>\n
This will create and assemble your compiled files to _build\/prod\/rel\/my_api\/bin\/my_api (obviously replacing the last part with your app name). The results of a release build show using<\/p>\n
Note: Replace \/prod\/ with \/dev\/ above etc. as per the environment you’ve compiled for<\/em><\/p>\n
\r\n_build\/prod\/rel\/my_api\/bin\/my_api start\r\n<\/pre>\n
to start your application, this will need start a server. By default the above does not start a server so instead we need to set the following environment variable<\/p>\n
\r\nexport PHX_SERVER=true\r\n<\/pre>\n
You’ll also able to run following it will automatically generate the bin\/server and sets the PHX_SERVER environment variable<\/p>\n
\r\nmix phx.gen.release\r\n<\/pre>\n
One last thing, you may find when you use the start<\/em> command (against PROD) that this fails saying you are missing the SECRET_KEY_BASE. We can generate this using<\/p>\n
\r\nmix phx.gen.secret\r\n<\/pre>\n
Then simply <\/p>\n
\r\nexport SECRET_KEY_BASE=your-generated-key\r\n<\/pre>\n
This is for signing cookies etc. and you can see where the exception comes from within the runtime.exs file. This is set as an environment variable, best not to check into source control.<\/p>\n
Dockerizing our service<\/strong><\/p>\n
Okay, it’s not Elixir specific, but I feel that the natural conclusion to our API\/service development is to have it all running in a container. Let’s start by creating a container image based upon the build and using the phx.server call…<\/p>\n
Create yourself a Dockerfile which looks like this<\/p>\n
\r\nFROM elixir:latest\r\n\r\nRUN mkdir \/app\r\nCOPY . \/app\r\nWORKDIR \/app\r\n\r\nRUN mix local.hex --force\r\nRUN mix do compile\r\n\r\nEXPOSE 4000\r\n\r\nCMD ["mix", "phx.server"]\r\n<\/pre>\n
I’m assuming we’re going to stick with port 4000 in the above and in the commands below, so I’ll document this via the EXPOSE command.<\/p>\n
Now to build and run our container let’s use the following<\/p>\n
\r\ndocker build -t pp\/my-api:0.1.0 .\r\ndocker run --rm --name my-api -p 4000:4000 -d pp\/my-api:0.1.0\r\n<\/pre>\n
Now you should be able to uses http:\/\/localhost:4000 to access your shiny new Elixir\/Phoenix API\/service.<\/p>\n
Note: Remember that if you cannot access the service outside of the docker image, ensure you’ve set the http ip in dev.exs to 0.0.0.0<\/em><\/p>\n
If we want to instead containerize our release build then we could use the following<\/p>\n
\r\nFROM elixir:latest\r\n\r\nENV PHX_SERVER=true\r\n\r\nRUN mkdir \/app\r\nCOPY \/_build\/dev\/ \/app\r\nWORKDIR \/app\/rel\/my_api\/bin\r\n\r\nEXPOSE 4000\r\n\r\nCMD [".\/my_api", "start"]\r\n<\/pre>\n
Again using the previous build and run commands, will start the server (if all went to plan).<\/p>\n
Code<\/strong><\/p>\n
Code is available in my GitHub blog project repo<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Most languages which I start to learn, I’ve found I learn the basics of the language (enough to feel at relative ease with the language) but then want to see it in real world scenarios. One of those is usually a web API or the likes. So today I’m looking at using Elixir along with […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[730,731,356],"tags":[],"class_list":["post-10948","post","type-post","status-publish","format-standard","hentry","category-elixir","category-phoenix","category-web-api"],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/10948","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/comments?post=10948"}],"version-history":[{"count":5,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/10948\/revisions"}],"predecessor-version":[{"id":11771,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/10948\/revisions\/11771"}],"wp:attachment":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/media?parent=10948"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/categories?post=10948"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/tags?post=10948"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}