Building an upgrade with Distillery

5 min readJul 28, 2017

Every alchemist requires good tools, and one of the greatest tools in the alchemist’s disposal is the distillery. The purpose of the distillery is to take something and break it down to its component parts, reassembling it into something better, more powerful. That is exactly what this project does — it takes your Mix project and produces an Erlang/OTP release, a distilled form of your raw application’s components; a single package which can be deployed anywhere, independently of an Erlang/Elixir installation. No dependencies, no hassle.
Distillery

In a previous post we talked a little about distillery and how to create a release for an Elixir application.

Today, we are going to make a couple of modifications to that application.

Change our home page
Add a new module that prints the current time.

New home page

First we need to change the home page of our application from this

to this

For that, we need to visit bootstrap examples grid, open the source code and copy everything inside the <div class="container"> tag. If you don’t know how to do it, just click in the URL, then press ⌘ + ⌥ + U, find <div class="container"> tag inside body and copy it.

Then open app.html.eex file inside web/templates/layout and paste it inside the body tag.

Start your application and you will see the following

We are almost done with this change, the next thing we need to do is copy the css. Open the source code again (⌘ + ⌥ + U) then find grid.css and open it in another tab. Copy the content and paste it at the end of the priv/static/css/app.css file. If you want, you can delete from line number 11 to 82.

Return to your browser and you should see the complete change

Timex Module

Now we are going to add a new function. For that, we will create a new file inside lib named as timex.ex. Then we just add the following:

defmodule Todo.Timex do

  def current_datetime do
    DateTime.utc_now
    |> DateTime.to_iso8601
  end

end

Binary generation

With that in place, we proceed to update our version in mix.exs as follows

Once we have done with these changes, we proceed to create our new binary. For that we run our server as in the previous example but in foreground mode. That is with PORT=4000 _build/prod/rel/todo/bin/todo foreground.

Now we just execute the following command MIX_ENV=prod mix release --upgrade --env=prod

❯ MIX_ENV=prod mix release --upgrade --env=prod
Compiling 11 files (.ex)
Generated todo app
==> Assembling release..
==> Building release todo:0.0.2 using environment prod
==> Including ERTS 8.3 from /usr/local/Cellar/erlang/19.3/lib/erlang/erts-8.3
==> Generated .appup for todo 0.0.1 -> 0.0.2
==> Relup successfully created
==> Packaging release..
==> Release successfully built!
    You can run it in one of the following ways:
      Interactive: _build/prod/rel/todo/bin/todo console
      Foreground: _build/prod/rel/todo/bin/todo foreground
      Daemon: _build/prod/rel/todo/bin/todo start

If you return to your web browser you will see the default page as the begining, but that is not a failure or an error. So, what happened here? Well, with the previous command we just create the binary and that is the first step.

Release upgrade

For see our changes there are two options:

The easier one is just restart our server. To achieve that, we need to use the stop command PORT=4000 _build/prod/rel/todo/bin/todo stop then we start our server again PORT=4000 _build/prod/rel/todo/bin/todo console.

There is a command for restarting our server called (yes, you guessed) restart But that command is useless for this.

But, what happen if “restarting” our server is not an option? Well, you are lucky, Erlang has the ability to make what they call HOT DEPLOY. That means that you don’t need to restart the whole application for having the latest changes.

The only thing you need to do is run the following command

❯ _build/prod/rel/todo/bin/todo upgrade 0.0.2
Release 0.0.2 not found, attempting to unpack releases/0.0.2/todo.tar.gz
Unpacked successfully: "0.0.2"
Release 0.0.2 is already unpacked, now installing.
Installed Release: 0.0.2
Made release permanent: "0.0.2"

Verifying update

Now return to your web browser and you will see the previous changes that we make.

But, how can I test the new function? Well for that, we need to connect to the console’s application. After that we can test our new function:

❯ _build/prod/rel/todo/bin/todo remote_consoleErlang/OTP 20 [erts-9.0] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]

Interactive Elixir (1.5.0) - press Ctrl+C to exit (type h() ENTER for help)iex(todo@127.0.0.1)1> Todo.Timex.current_datetime
"2017-07-27T17:53:11.493503Z"iex(todo@127.0.0.1)2>

And that’s all!

Conclusions

In this post, we learned how to create a binary upgrade for an application. As well as how to “deploy” those changes without restarting the whole system and how we can connect to a running elixir environment for testing our new function.

With those new abilities we can move to learn how to make a deploy to another environment from our console. And for that we are going to use a tool called eDeliver

But, for this post we are done, I hope you can find interesting and helpful. If you have any comments or any doubts please let me know.

And as with the previous post, in case you have troubles, here is the repository to download this example.

See you next time. Good luck and have fun!