Using Elixir Releases

Configuration and Secrets

Gigalixir auto-detects that you want to use Elixir Releases if you have a config/releases.exs file, so let’s create one.


Elixir 1.11 adds config/runtime.exs. If you use that instead, then you’ll want to specify buildpacks since we can no longer detect if you want releases or mix mode. See Specify Buildpacks (optional).

echo "import Config" > config/releases.exs

The only configuration change we really need to do now is make sure the web server is started. Add the following to your releases.exs.

config :gigalixir_getting_started, GigalixirGettingStartedWeb.Endpoint,
  server: true,
  http: [port: {:system, "PORT"}], # Needed for Phoenix 1.2 and 1.4. Doesn't hurt for 1.3.
  url: [host: System.get_env("APP_NAME") <> "", port: 443]
  1. Replace :gigalixir_getting_started with your app name e.g. :my_app

  2. Replace GigalixirGettingStartedWeb.Endpoint with your endpoint module name. You can find your endpoint module name by running something like

    grep -R "defmodule.*Endpoint" lib/

    Phoenix 1.2, 1.3, and 1.4 give different names so this is a common source of errors.

If you’re using a free tier database, be sure to also set your pool size to 2 in prod.exs.

You don’t have to worry about setting your SECRET_KEY_BASE config because we generate one and set it for you.


Let’s make sure everything works.

First, try building static assets

mix deps.get
cd assets
npm install
npm run deploy
cd ..
mix phx.digest

and building a release locally

export SECRET_KEY_BASE="$(mix phx.gen.secret)"
export DATABASE_URL="postgresql://user:pass@localhost:5432/foo"
MIX_ENV=prod mix release

and running it locally

MIX_ENV=prod APP_NAME=gigalixir_getting_started PORT=4000 _build/prod/rel/gigalixir_getting_started/bin/gigalixir_getting_started start

Don’t forget to replace gigalixir_getting_started with your own app name. Also, change/add the environment variables as needed.

Check it out.

curl localhost:4000

If that didn’t work, the first place to check is prod.exs. Make sure you have server: true somewhere and there are no typos.

Also check out Troubleshooting.

If it still doesn’t work, don’t hesitate to contact us.

If everything works, commit the changes

git add config/prod.exs assets/package-lock.json config/releases.exs
git commit -m 'releases configuration'

Continue to Set Up App for Deploys.

Specify Buildpacks (optional)

We rely on buildpacks to compile and build your release. We auto-detect a variety of buildpacks so you probably don’t need this, but if you want to specify your own buildpacks create a .buildpacks file with the buildpacks you want. For example,


It’s important that you do not include release=true in your elixir_buildpack.config. The causes the elixir buildpack to generate a release which conflicts with the release generated by gigalixir-buildpack-releases.


If you need to configure your release in mix.exs make sure the release name matches your app name (also defined in mix.exs, not your gigalixir app name).

heroku-buildpack-phoenix-static is optional if you do not have Phoenix static assets. For more information about buildpacks, see Life of a Deploy.

Note, that the command that gets run in production depends on what your last buildpack is.

  • If the last buildpack is gigalixir-buildpack-releases, then the command run will be /app/bin/foo start.
  • If the last buildpack is heroku-buildpack-phoenix-static, then the command run will be mix phx.server.
  • If the last buildpack is heroku-buildpack-elixir, then the command run will be mix run --no-halt.

If your command is mix run --no-halt, but you are running Phoenix (just not the assets pipeline), make sure you set server: true in prod.exs.