Elixir Functions


Deploying Elixir Applications with Distillery

When it comes to deploying Elixir applications, there’s a remarkable tool that stands out: Distillery. This guide will take you through the ins and outs of deploying Elixir applications using Distillery, covering everything from installation to advanced deployment strategies. Whether you’re a seasoned Elixir developer or just getting started, this comprehensive guide will equip you with the knowledge and skills to deploy your applications with confidence.

Deploying Elixir Applications with Distillery

1. Understanding Distillery

1.1. What is Distillery?

Distillery is an essential tool in the Elixir ecosystem that facilitates the creation and deployment of standalone, production-ready releases of your Elixir applications. A release is a self-contained package that includes your application code, runtime, and all required dependencies. This ensures consistency across different environments and simplifies deployment.

1.2. Why Use Distillery for Deployments?

  • Isolation: Distillery releases bundle everything needed to run your application, eliminating dependency conflicts and ensuring consistent behavior.
  • Efficiency: Releases are pre-compiled and optimized, leading to faster startup times and reduced memory consumption.
  • Version Management: Distillery enables easy management of different release versions, allowing for seamless upgrades and rollbacks.
  • Deployment Flexibility: You can deploy releases to various environments, including bare-metal servers, virtual machines, and containers.

2. Getting Started

2.1. Installing Distillery

To begin using Distillery, you need to add it as a dependency to your Elixir project. In your mix.exs file, add the following line to your deps function:

{:distillery, "~> 2.0"}

After adding the dependency, run mix deps.get to fetch and install Distillery.

2.2. Configuring Your Elixir Application

Distillery requires a configuration file to define how your release should be built. Create a rel/config.exs file in your project and configure essential settings such as the release name, version, and environment variables.

use Mix.Releases.Config,
  release: "my_app",
  version: "1.0.0",
  environment: :prod,
  start_permanent: Mix.env() == :prod

3. Building Releases

3.1. Creating a Release

To build a release using Distillery, execute the following command:

mix release

This command packages your application code along with its dependencies and the runtime into a standalone release package. The resulting release can be found in the _build/prod/rel/my_app directory.

3.2. Customizing Releases with Configuration

Distillery allows you to customize your release by specifying various configuration options. These options can be defined in your rel/config.exs file. For instance, you can configure environment-specific settings, startup scripts, and more.

environment :prod do
  set include_erts: true
  set include_src: false
  set cookie: :"your_secret_cookie"

3.3. Including Runtime Dependencies

If your application relies on native code or external binaries, you can include them in your release by configuring the :included_erts and :include_erts options. This ensures that your release has all the necessary components to run correctly.

4. Deployment Strategies

4.1. Hot Upgrades with Distillery

One of the standout features of Elixir and Erlang is their support for hot code upgrades. Distillery makes it straightforward to perform hot upgrades without downtime. By building a release with a unique version and using a proper supervision setup, you can upgrade your application without interrupting its operation.

4.2. Blue-Green Deployments

Distillery also supports blue-green deployments, a strategy where you have two identical production environments—blue (current) and green (new). By deploying the new release to the green environment, you can perform thorough testing before switching traffic from blue to green.

4.3. Containerization with Docker

To further streamline your deployment process, you can containerize your Distillery releases using Docker. Docker containers encapsulate your application, its runtime, and dependencies, ensuring consistency across different environments.

5. Deployment to Production

5.1. Setting Up Production Environment

Before deploying your Distillery release to production, ensure that you have a well-configured production environment. This includes setting up databases, networking, security settings, and load balancers.

5.2. Preparing Your Application for Production

To optimize your application for production, consider tweaking Elixir settings like memory limits and process flags. Perform load testing to identify potential bottlenecks and optimize your application accordingly.

5.3. Deploying Your Release

To deploy your Distillery release to a production environment, transfer the release package to your target server and start the application using the provided startup scripts. It’s important to follow the best practices for your chosen deployment strategy, whether it’s hot upgrades, blue-green deployments, or Docker containerization.

6. Monitoring and Maintenance

6.1. Monitoring Elixir Applications

Implement robust monitoring for your deployed application. Tools like Prometheus and Grafana can help you collect metrics and visualize the performance of your application and underlying infrastructure.

6.2. Managing Upgrades and Rollbacks

Distillery simplifies the process of managing upgrades and rollbacks. By maintaining different release versions and following well-defined procedures, you can minimize downtime and ensure smooth transitions.

6.3. Scaling Your Deployed Application

As your application gains popularity, you may need to scale it horizontally. Use load balancers and clustering to distribute traffic across multiple instances of your application.

7. Troubleshooting and Best Practices

7.1. Common Deployment Issues and Solutions

Deployment may come with its fair share of challenges. It’s crucial to be prepared for potential issues such as environment mismatches, dependency conflicts, or performance bottlenecks. Familiarize yourself with common problems and their solutions.

7.2. Best Practices for Smooth Deployments

Follow best practices to ensure smooth and hassle-free deployments. This includes maintaining proper documentation, automating deployment processes, and regularly testing your deployment pipeline.


Deploying Elixir applications with Distillery empowers you to create reliable, optimized, and efficient release packages. This guide has taken you through the entire deployment process, from installing Distillery to implementing advanced deployment strategies. By leveraging Distillery’s capabilities, you can confidently deploy your Elixir applications to production environments, delivering exceptional performance and reliability to your users. Remember, continuous learning and hands-on experience are key to mastering the art of deploying Elixir applications with Distillery.

Previously at
Flag Argentina
time icon
Tech Lead in Elixir with 3 years' experience. Passionate about Elixir/Phoenix and React Native. Full Stack Engineer, Event Organizer, Systems Analyst, Mobile Developer.