Modifying an Existing App to Run on Gigalixir

Whether you have an existing app or you just ran mix, the goal of this guide is to get your app ready for deployment on Gigalixir. We assume that you are using Phoenix here. If you aren’t, feel free to contact us for help. As long as your app is serving HTTP traffic on $PORT, you should be fine.


If you have an umbrella app, be sure to also see How do I deploy an umbrella app?.

Mix vs Distillery vs Elixir Releases

Probably the hardest part of deploying Elixir is choosing which method of deploying you prefer, but don’t worry, it’s easy to change your mind later and switch. We typically recommend elixir releases because it is easy to set up and unlocks the most important features like observer. Here is a comparison table to help you choose.

Feature Mix Elixir Releases Distillery
Hot Upgrades     YES
Remote Observer   YES YES
Mix Tasks YES    
Built-in to Elixir YES YES  
Easy Configuration[1] YES    
Clustering YES YES YES
gigalixir ps:migrate YES YES YES
Fast startup[2]   YES YES
Hidden Source Code[3]   YES YES

If you choose mix, see Using Mix.

If you choose Elixir releases, see Using Elixir Releases.

If you choose distillery, see Using Distillery.

[1] We say easy configuration here because some customers get confused about the difference between prod.exs and releases.exs. Distillery can be even more confusing with its REPLACE_OS_VARS syntax. [2] Due to smaller slug sizes [3] Mix deploys the source code to the runtime container rather than just the compiled BEAM files

How do I switch to mix mode?

Mix mode is sort of the default, but we automatically detect and switch you to distillery mode if you have a rel/config.exs file so one option is to delete that file. We also automatically detect and switch you to Elixir releases mode if you have a config/releases.exs file so also be sure that file is deleted.

If you don’t want to delete those files, you can manually force mix mode by specifying the mix buildpack. Create a .buildpacks file and make sure you have something like the following. Notice that the last buildpack is the mix buildpack.

If you wanted to force distillery or Elixir releases, you’d want the last buildpack to be either the or the buildpacks, respectively.