Home / Knowledge / Migrating from Distillery to Releases

Migrating from Distillery to Releases

Jan 15, 2025

Distillery is a popular tool for building releases in Elixir. However, it is no longer being actively maintained. This article will guide you through the process of migrating from Distillery to Elixir Releases on Gigalixir.

Distillery was last actively developed in 2019. It is officially supported only up to the stack gigalixir-22, which reaches EOL in early 2027. Additionally, Distillery does not work with OTP 25 or greater.

Elixir Releases provides similar functionality to Distillery, allowing for quick startup times by compiling releases in a comparable manner.

This guide provides step-by-step instructions to transition from Distillery to Elixir Releases on Gigalixir.

Remove Distillery

The first step in migrating is to remove references to Distillery from your repository.

Remove distillery from your mix.exs and mix.lock files.
Delete the rel directory from your project.

Move Runtime Configurations

When using Elixir Releases, ensure that any application configurations dependent on environment variables are moved to the config/runtime.exs file.
This file is evaluated at runtime and has access to environment variables.
Leaving these configurations in config/prod.exs or config/config.exs will result in them not being available at runtime.

Example:

# config/runtime.exs
import Config

if config_env() == :prod do
  # Move any configuration from config/prod.exs or config/config.exs
  # that depends on an environment variable here, for example:
  config :my_app, MyApp.Repo,
    url: System.get_env("DATABASE_URL"),
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10")
end

Specify Elixir Releases

Next, signal to the build system that you want to use Elixir Releases instead of Distillery.

Buildpacks File

If you are using a .buildpacks file, update the line referencing distillery to:

https://github.com/gigalixir/gigalixir-buildpack-releases

Gigalixir 22 or Earlier

If you are not using a .buildpacks file and are on the gigalixir-22 stack or earlier, create a config/releases.exs file to instruct the build system to use Elixir Releases.

echo "# this file is here so Gigalixir uses Elixir Releases in the build process" > config/releases.exs

Gigalixir 24 and greater

If you are not using a .buildpacks file and are on the gigalixir-24 stack or newer, Elixir Releases is the default build option. Congratulations, there is nothing more to do here!

Deploy a Fresh Build

For your first deployment using Elixir Releases, we recommend cleaning the build cache. This ensures the build system starts fresh and uses the new build process.

git -c http.extraheader="GIGALIXIR-CLEAN: true" push gigalixir

After pushing the changes, your application will be built using Elixir Releases. Monitor the deployment to ensure the application starts successfully:

# Verify the new process starts up successfully
gigalixir ps

# Check the logs for any errors
gigalixir logs

Need help?

If you need help migrating from Distillery to Releases on Gigalixir, please reach out to our support team.

⟵ PREV