Distillery

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.

This is a pure-Elixir, dependency-free implementation of release generation for Elixir projects. It is currently a standalone package, but may be integrated into Mix at some point in the future.

Installation

Distillery requires Elixir 1.6 or greater. It works with Erlang 20+.

defp deps do
  [{:distillery, "~> 2.0"}]
end

Just add as a mix dependency and use mix release.

If you are new to releases or Distillery, please review the documentation, it covers just about any question you may have!

Upgrading From 1.5.x

Many things have changed since the last 1.5 release, with a number of deprecations, improvements, and new features. The following is a guide to the things which you will need to change coming from 1.5, whether using Distillery directly, or writing tools which build on Distillery:

Custom Commands

In 1.5.x, you may have used any of the following helpers in the bin/myapp script:

command MODULE FUN
rpc MODULE FUN ARGS
rpcterms MODULE FUN TERM
eval EXPR

These have seen breaking changes:

command MODULE FUN (soft deprecated) - same as old version, switch to eval
rpcterms MODULE FUN TERM (hard deprecated) - removed entirely from 2.x, use rpc instead
rpc EXPR - takes a string of Elixir code, and executes it on the remote node
eval EXPR - takes a string of Elixir code, and executes it on a clean node, with no applications started (similar to how command worked)

Here are some examples:

command Elixir.MyApp.Release.Tasks migrate becomes eval 'MyApp.Release.Tasks.migrate()'
rpc 'Elixir.Application' get_env myapp foo becomes rpc 'Application.get_env(:myapp, :foo)'
rpcterms calendar valid_date '{2018,1,1}' becomes rpc ':calendar.valid_date({2017,1,1})'

You may also pass --file path/to/script.exs to either rpc or eval to execute an Elixir script from a file.

There are now just two commands, rpc and eval, both of which work the exact same way, with the only distinction being the execution environment of the provided script or expression - local for eval and remote for rpc. With eval, the execution environment has all code available, but no applications started, so it is ideal for things like migrations.

Hooks

If you were using set <event>_hook: "path/to/script.sh" where <event> was any of the lifecycle events you could hook into, e.g. pre_start; you must now use set <event>_hooks: "path/to/directory/of/hooks". The path given must be a directory, and should contain all of the hooks for that event. The old options have been removed.

Executables

The exec_opts option is deprecated, and combined with the executable option. You now should use set executable: [enabled: true, transient: boolean] to build an executable release with the relevant options set.

New Features

The following have been added, and you should take a look in the docs for more information as they are big quality of life improvements!

Config Providers! This is a framework for format-agnostic, source-agnostic runtime configuration providers, which allow you to fetch configuration and push it into the application env before applications in the system have booted. See the docs and the Mix.Releases.Config.Provider moduledoc for more information. If you are curious about what a custom provider looks like, check out this library, which has a provider for TOML. Distillery also contains a provider for Mix.Config out of the box.
Appup Transforms! This is a plugin system for programmatically modifying appups during a release build. Use this to tweak the way appups are generated for your applications.
A new mix task! mix release.gen.appup allows you to generate appups for an application and place it under rel in a new directory which is checked by Distillery when building upgrade releases. This directory can be source controlled, and the generated files can be modified as needed. This is a much needed improvement for those performing hot upgrades!
PID file creation when -kernel pidfile "path" is given in vm.args, or PIDFILE=path is exported in the system environment.

If you encounter an issue that is not covered here or in the documentation, please open an bug on the issue tracker!

Community/Questions/etc.

If you have questions or want to discuss Distillery, releases, or other deployment related topics, a good starting point is the Deployment section of ElixirForum, which can be found here.

I can often be found in IRC on freenode, in the #elixir-lang channel, and there is also an Elixir Slack channel as well, though I don't frequent that myself, there are many people who can answer questions there.

Failing that, feel free to open an issue on the tracker with questions, and I'll do my best to get to it in a timely fashion!

License

MIT. See the LICENSE.md in this repository for more details.

adkron/distillery