{"id":9051,"date":"2019-05-29T10:26:43","date_gmt":"2019-05-29T13:26:43","guid":{"rendered":"http:\/\/blog.plataformatec.com.br\/?p=9051"},"modified":"2019-11-14T11:49:55","modified_gmt":"2019-11-14T13:49:55","slug":"updating-hex-pm-to-use-elixir-releases","status":"publish","type":"post","link":"http:\/\/blog.plataformatec.com.br\/2019\/05\/updating-hex-pm-to-use-elixir-releases\/","title":{"rendered":"Updating Hex.pm to use Elixir releases"},"content":{"rendered":"<p><a href=\"http:\/\/blog.plataformatec.com.br\/2019\/04\/whats-new-in-elixir-apr-19\/\" target=\"_blank\" rel=\"noopener noreferrer\">Elixir v1.9 will ship with releases support<\/a> and in this blog post we want to show how we have used this exciting new feature on the Hex.pm project.<\/p>\n<h2>Installing Elixir master<\/h2>\n<p>(Update: This section is no longer relevant since v1.9 is already out!)<\/p>\n<p>Since Elixir v1.9 is not out yet, we need to use the development version. Locally, my preferred approach is to use the <a href=\"https:\/\/github.com\/asdf-vm\/asdf-elixir\" target=\"_blank\" rel=\"noopener noreferrer\">Elixir plugin<\/a> for the <a href=\"https:\/\/github.com\/asdf-vm\/asdf\" target=\"_blank\" rel=\"noopener noreferrer\">asdf-vm<\/a> version manager.<\/p>\n<p>Here&#8217;s a couple of ways we may use asdf to install recent development versions:<\/p>\n<pre><code># install latest master\n$ asdf install elixir master\n$ asdf local elixir master\n\n# or, install particular revision:\n$ asdf install elixir ref:b8b7e5a\n$ asdf local elixir ref:b8b7e5a\n<\/code><\/pre>\n<p>Per &#8220;Deployment&#8221; section of <a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.html?#module-deployments\" target=\"_blank\" rel=\"noopener noreferrer\"><code>mix release<\/code><\/a> documentation:<\/p>\n<blockquote><p>A release is built on a host, a machine which contains Erlang, Elixir, and any other dependencies needed to compile your application. A release is then deployed to a target, potentially the same machine as the host, but usually separate, and often there are many targets (either multiple instances, or the release is deployed to heterogeneous environments).<\/p><\/blockquote>\n<p>We deploy Hex.pm using Docker containers and <a href=\"https:\/\/github.com\/hexpm\/hexpm\/blob\/master\/Dockerfile\" target=\"_blank\" rel=\"noopener noreferrer\">we needed to change our Dockerfile<\/a>. If you&#8217;re deploying using buildpacks (e.g. to Heroku or Gigalixir), it should be as simple as setting <code>elixir_version=master<\/code> in your <code>elixir_buildpack.config<\/code>.<\/p>\n<h2>Setting up releases<\/h2>\n<p>Elixir 1.9 ships with two new Mix tasks to work with releases:<\/p>\n<ul>\n<li><a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.Init.html\" target=\"_blank\" rel=\"noopener noreferrer\"><code>mix release.init<\/code><\/a> &#8211; generates sample files for releases<\/li>\n<li><a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.html\" target=\"_blank\" rel=\"noopener noreferrer\"><code>mix release<\/code><\/a> &#8211; builds the release<\/li>\n<\/ul>\n<p>The sample files generated by <code>mix release.init<\/code> are optional, if they are not present in your project then the release will be built with default options.<\/p>\n<p>On Hex.pm, previously we were building releases using <a href=\"https:\/\/hex.pm\/packages\/distillery\" target=\"_blank\" rel=\"noopener noreferrer\">Distillery<\/a> and to work with Elixir releases we needed to make a few small tweaks. Here are the main ones:<\/p>\n<ul>\n<li>add <code>:releases<\/code> section to <code>mix.exs<\/code> &#8211; this is an optional step but since we don&#8217;t deploy on Windows, we only need to generate executable files for UNIX-like systems<\/li>\n<li>replace <code>rel\/vm.args<\/code> with <code>rel\/vm.args.eex<\/code><\/li>\n<li>replace <code>rel\/hooks\/pre_configure<\/code> with <code>rel\/env.sh.eex<\/code><\/li>\n<li>add <code>config\/releases.exs<\/code> for runtime configuration of the release<\/li>\n<li>remove Distillery dependency (remember to <code>mix deps.unlock<\/code> it!)<\/li>\n<\/ul>\n<p>See the <a href=\"https:\/\/github.com\/hexpm\/hexpm\/pull\/801\" target=\"_blank\" rel=\"noopener noreferrer\">&#8220;Replace Distillery with Elixir releases&#8221; PR on Hex.pm repo<\/a> for more details.<\/p>\n<p>We now have a few files that deal with configuring our app\/release, let&#8217;s take a step back and see what they can do:<\/p>\n<ul>\n<li><a href=\"https:\/\/github.com\/hexpm\/hexpm\/blob\/master\/config\/prod.exs\" target=\"_blank\" rel=\"noopener noreferrer\"><code>config\/prod.exs<\/code><\/a> &#8211; provides build-time application configuration<\/li>\n<li><a href=\"https:\/\/github.com\/hexpm\/hexpm\/blob\/master\/config\/releases.exs\" target=\"_blank\" rel=\"noopener noreferrer\"><code>config\/releases.exs<\/code><\/a> &#8211; provides runtime application configuration. We&#8217;re using the new <a href=\"https:\/\/hexdocs.pm\/elixir\/master\/Config.html\" target=\"_blank\" rel=\"noopener noreferrer\"><code>Config<\/code><\/a> module and the <a href=\"https:\/\/hexdocs.pm\/elixir\/master\/System.html?#fetch_env!\/1\" target=\"_blank\" rel=\"noopener noreferrer\"><code>System.fetch_env!\/1<\/code><\/a> function, also introduced in Elixir v1.9.0, to conveniently return the environment variable if set, or raise an error.<\/li>\n<li><a href=\"https:\/\/github.com\/hexpm\/hexpm\/blob\/master\/rel\/vm.args.eex\" target=\"_blank\" rel=\"noopener noreferrer\"><code>rel\/vm.args.eex<\/code><\/a> &#8211; provides a static mechanism for configuring the Erlang Virtual Machine and other runtime flags. For now, we use the defaults but if down the line we&#8217;d tune the VM, we&#8217;d set the options here.<\/li>\n<li><a href=\"https:\/\/github.com\/hexpm\/hexpm\/blob\/master\/rel\/env.sh.eex\" target=\"_blank\" rel=\"noopener noreferrer\"><code>rel\/env.sh.eex<\/code><\/a> &#8211; provides a dynamic mechanism for setting up the VM, runtime flags, and environment variables.<\/li>\n<\/ul>\n<p><code>RELEASE_NODE<\/code> and <code>RELEASE_COOKIE<\/code> variables are used by the release script, see <a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.html?#module-environment-variables\" target=\"_blank\" rel=\"noopener noreferrer\">&#8220;Environment variables&#8221;<\/a> section in the documentation for all recognized variables. The <code>POD_A_RECORD<\/code> variable we have there is specific to our deployment environment on Hex.pm, we deploy it to Google Kubernetes Engine.<\/p>\n<p>See <a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.html?#module-application-configuration\" target=\"_blank\" rel=\"noopener noreferrer\">&#8220;Application configuration&#8221;<\/a> and <a href=\"https:\/\/hexdocs.pm\/mix\/master\/Mix.Tasks.Release.html?#module-vm-args-and-env-sh-env-bat\" target=\"_blank\" rel=\"noopener noreferrer\">&#8220;vm.args and env.sh (env.bat)&#8221;<\/a> sections for more information.<\/p>\n<p>Finally, we use the <code>mix release<\/code> task to actually assemble the release:<\/p>\n<pre><code>$ mix release\n* assembling hexpm-0.0.1 on MIX_ENV=dev\n* using config\/releases.exs to configure the release at runtime\n* creating _build\/dev\/rel\/hexpm\/releases\/0.0.1\/vm.args\n* creating _build\/dev\/rel\/hexpm\/releases\/0.0.1\/env.sh\n\nRelease created at _build\/dev\/rel\/hexpm!\n\n# To start your system\n_build\/dev\/rel\/hexpm\/bin\/hexpm start\n\nOnce the release is running:\n\n# To connect to it remotely\n_build\/dev\/rel\/hexpm\/bin\/hexpm remote\n\n# To stop it gracefully (you may also send SIGINT\/SIGTERM)\n_build\/dev\/rel\/hexpm\/bin\/hexpm stop\n\nTo list all commands:\n\n_build\/dev\/rel\/hexpm\/bin\/hexpm\n<\/code><\/pre>\n<h2>Running the release<\/h2>\n<p>The generated release script (<code>bin\/hexpm<\/code>) has many commands:<\/p>\n<pre><code>$ _build\/dev\/rel\/hexpm\/bin\/hexpm\nUsage: hexpm COMMAND [ARGS]\n\nThe known commands are:\n\nstart          Starts the system\nstart_iex      Starts the system with IEx attached\ndaemon         Starts the system as a daemon\ndaemon_iex     Starts the system as a daemon with IEx attached\neval \"EXPR\"    Executes the given expression on a new, non-booted system\nrpc \"EXPR\"     Executes the given expression remotely on the running system\nremote         Connects to the running system via a remote shell\nrestart        Restarts the running system via a remote command\nstop           Stops the running system via a remote command\npid            Prints the OS PID of the running system via a remote command\nversion        Prints the release name and version to be booted\n<\/code><\/pre>\n<p>In our Hex.pm deployment we have used two of these commands for now:<\/p>\n<ul>\n<li><code>bin\/hexpm start<\/code> &#8211; we use it as the start command to be run in our Docker container<\/li>\n<li><code>bin\/hexpm eval<\/code> &#8211; we use it to run DB migrations and other maintenance scripts. For migrations, the command is: <code>bin\/hexpm eval 'Hexpm.ReleaseTasks.migrate()'<\/code>.<\/li>\n<\/ul>\n<h2>Summary<\/h2>\n<p>In this blog post we&#8217;ve walked through using Elixir releases on an existing project, Hex.pm. We&#8217;ve installed the development version of Elixir, configured the release, and adjusted our deployment setup to use it. Hex.pm was previously using Distillery, and with minimal changes we were able to update it to use built-in releases support.<\/p>\n<p>Overall, I\u2019m very happy about this change. We\u2019ve ended up with about the same amount of configuration code, but I think it\u2019s a little bit better structured and more obvious.<\/p>\n<p>I especially like new conventions around configuration. Where previously we used workarounds like <code>config :app, {:system, \"ENV_VAR\"}<\/code> and <code>\"${ENV_VAR}\"<\/code> (and <code>REPLACE_OS_VARS=true<\/code>), we now have a clear distinction between build-time and runtime configuration. <a><code>mix release<\/code><\/a> documentation does a really good job of explaining configuration aspects in particular but also the whole release process in general.<\/p>\n<p>Building the release is now faster too, on my machine ~2.5s now vs ~5.5s before. Granted, it\u2019s probably the least concern but it\u2019s a nice cherry on top nonetheless.<\/p>\n<p>As of this writing, Hex.pm is already deployed using Elixir releases. Now your turn &#8211; try out releases on your project! (And if something goes wrong, <a href=\"https:\/\/github.com\/elixir-lang\/elixir\/issues\/new\" target=\"_blank\" rel=\"noopener noreferrer\">submit an issue<\/a>!)<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Elixir v1.9 will ship with releases support and in this blog post we want to show how we have used this exciting new feature on the Hex.pm project. Installing Elixir master (Update: This section is no longer relevant since v1.9 is already out!) Since Elixir v1.9 is not out yet, we need to use the &#8230; <a class=\"read-more-link\" href=\"http:\/\/blog.plataformatec.com.br\/2019\/05\/updating-hex-pm-to-use-elixir-releases\/\">\u00bb<\/a><\/p>\n","protected":false},"author":70,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"ngg_post_thumbnail":0,"footnotes":""},"categories":[1],"tags":[143],"aioseo_notices":[],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/9051"}],"collection":[{"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/users\/70"}],"replies":[{"embeddable":true,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/comments?post=9051"}],"version-history":[{"count":22,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/9051\/revisions"}],"predecessor-version":[{"id":9547,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/posts\/9051\/revisions\/9547"}],"wp:attachment":[{"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/media?parent=9051"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/categories?post=9051"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/blog.plataformatec.com.br\/wp-json\/wp\/v2\/tags?post=9051"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}