Preparing a Phoenix 1.6 app for deployment with Elixir Releases

I'm going to prepare a Phoenix application for deployment.

Prerequisites

Ensure to have your Phoenix 1.6 app running locally.

Runtime configuration

When deploying to production is better to inject runtime info to the application when it starts instead of having that info hardcoded in the source code. We pass info to the app to affect the way it works depending on the environment we are deploying the app to (e.g. staging, production).

Elixir 1.11 has introduced a way to inject this runtime info easily with the config/runtime.exs config file. If you open that file you'll see that it obtains some values from environment variables. The default environment variables to configure are POOL_SIZE, PORT, DATABASE_URL and SECRET_KEY_BASE. We need to specify a value for those envvars if we want our deployment to work correctly.

For now we are going to test it locally, in our laptop. In a deployment service, like Gigalixir or Fly.io, those envvars are going to be provided when the app starts. We are going to do that manually here:

export POOL_SIZE=2export PORT=4001export DATABASE_URL=ecto://postgres:postgres@localhost/saturn_devexport SECRET_KEY_BASE=$(mix phx.gen.secret)

I have my database named locally saturn_dev and the user and password the ones shown. You can see your own connection parameters in config/dev.exs

Build in production mode

Compile elixir code

We can now get the production dependencies:

mix deps.get --only prodMIX_ENV=prod mix compile

Compile assets

If the project has JS, CSS or other assets you can also compile them with the esbuild wrapper that phoenix now uses:

MIX_ENV=prod mix assets.deploy

Test that the project starts in prod mode

By now, if you haven't closed the terminal, you'll have the previous envvars still defined. If you have closed the terminal, you need to set them again.

MIX_ENV=prod mix phx.server

If you go to http://localhost:4001/ you'll see the homepage of the app, but this time it is using the configuration that the config/runtime.exs read from the terminal when it started instead of using the config/dev.exs configuration. One thing you'll notice is that the LiveDashboard link is gone. This works only in dev mode.

Generate a release

We need to do an extra step before building the release using Elixir Releases. Open config/runtime.exs and uncomment the following line, in the section titled "Using releases"

config :saturn, SaturnWeb.Endpoint, server: true

This direct the app to start the webserver when running the release executable. When we used mix phx.server this was done for us. Now we need to explicitly enable it.

After saving those changes we can now generate the release:

MIX_ENV=prod mix release

Run the release

We can now run the release executable generated by the mix release task:

_build/prod/rel/saturn/bin/saturn start

If you go again to http://localhost:4001/ you'll see the app running, but this time from the self-contained bundle that the Elixir Releases generated for us.

You can put the contents of the _build/prod/rel/saturn folder in any production server and start it. You don't need anything else installed because this folder includes all the dependencies and binaries required to run the application.

You could do that manually, for example, by copying this folder to a DigitalOcean droplet or any other VPS provider, but there are better ways to do that.

I'll show you how to deploy to Gigalixir in a future post.

Miguel Cob