Modifying an Existing App to Run on Gigalixir

Whether you have an existing app or you just ran mix phx.new, the goal of this guide is to get your app ready for deployment on Gigalixir.

We assume that you are using Phoenix with Elixir and Gigalixir. If you aren’t, feel free to contact us for help with other frameworks.

However, as long as your app is serving HTTP traffic on $PORT, you should be fine.

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

Elixir Releases vs Mix vs Distillery

Deprecation Warning
Distillery is now considered DEPRECATED. The official notice is on Distillery’s github page.

Gigalixir is recommending users move to 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 Elixir Releases Mix Distillery
Hot Upgrades     YES
Remote Observer YES   YES
Mix Tasks   YES  
Built-in to YES YES  
Elixir      
Easy Configuration ¹   YES  
Clustering YES YES YES
gigalixir ps:migrate Fast YES YES YES
Fast startup ² YES   YES
Hidden Source Code ³ YES   YES

If you choose Elixir releases, see Modifying an App for Gigalixir using Elixir Releases or Phoenix Deploy with Releases.

If you want to use Mix, see Modifying an App for Gigalixir using Mix or Phoenix Deploy with Releases.

If you choose Distillery, see Modifying an App for Gigalixir using Distillery or Phoenix Deploy with Releases.

¹ 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.

² Due to smaller slug sizes.

³ Mix deploys the source code to the runtime container rather than just the compiled BEAM files

How Do I Switch to Modes?

Mix mode is the default, but we automatically detect automatically detect and switch you to Elixir Releases mode if you have a config/releases.exs file. To override that behavior, you just need to delete that file.

If you are newer versions of Elixir, you may have a config/runtime.exs file, but not a config/releases.exs. If you wish to use Elixir Releases, just add an empty config/runtime.exs file to your repoistory.

We also automatically switch to Distillery mode if you have a rel/config.exs file. To override that behavior, you just need to delete that file.

You can also specify your buildpacks specifically. You can find the default buildpacks for each mode in these docs: