The following instructions allow a user to go from zero to hero with Gigalixir, Phoenix, and Mix. This guide uses the latest versions:
- distillery 2.1.1
- elixir 1.14.5
- node 20.2.0
- phoenix 1.7.3
Distillery is incompatible with OTP 25 and newer, so this guide is using:
- erlang 24.3.4.11
Last updated/tested on 2023-05-30.
Gigalixir is recommending users move to Elixir Releases.
Prerequisites
This guide utilizes these tools:
With these tools set up, let’s get started!
Install Erlang, Elixir, and Node
Use ASDF and NVM to install the versions we want.
asdf install erlang 24.3.4.11
asdf install elixir 1.14.5
nvm install v20.2.0
Now set the versions as active.
asdf local erlang 24.3.4.11
asdf local elixir 1.14.5
nvm use v20.2.0
Install Phoenix Framework
Get the latest version of Phoenix and install it.
mix local.hex
mix archive.install hex phx_new
Create a new phoenix application
Create the phoenix application, in this case distillery_example
is the name of the application.
You will probably want use some other name.
mix phx.new distillery_example --install
cd distillery_example
git init
git add .
git commit -m "initial commit: mix phx.new"
Set the versions for the buildpacks to use
Gigalixir uses a buildpack system.
We can set the versions in the elixir_buildpack.config
and phoenix_static_buildpack.config
to ensure a consistent environment between development and production.
echo "elixir_version=1.14.5" > elixir_buildpack.config
echo "erlang_version=24.3.4.11" >> elixir_buildpack.config
echo "node_version=20.2.0" > phoenix_static_buildpack.config
git add elixir_buildpack.config phoenix_static_buildpack.config
git commit -m "set elixir, erlang, and node version"
Esbuild support
Gigalixir has esbuild installed, but we need to tell the buildpacks how to compile our assets.
mkdir -p assets
echo '{
"scripts": {
"deploy": "cd .. && mix assets.deploy && rm -f _build/esbuild"
}
}' > assets/package.json
git add assets/package.json
git commit -m "compile assets on build"
Add distillery
We need to add distillery to our mix.exs
file as a dependency.
You can do that manually or the following will add it to the top of the list.
sed -i '/{:phoenix, "~> .*"},/i \ {:distillery, "~> 2.1"},' mix.exs
Then we need to install the deps.
mix deps.get
mix distillery.init
To deploy with distillery we need to remove the config/runtime.exs
file, but keep the content.
cat config/runtime.exs >> config/prod.exs
rm config/runtime.exs
git add mix.exs mix.lock config/prod.exs config/runtime.exs rel/
git commit -m "add distillery"
Create the gigalixir app and database
The default phoenix application is going to require a DATABASE_URL. In the below example, we create a free tier database. If you plan to use this application for production, consider the [standard tier database].
APP_NAME=$(gigalixir create)
gigalixir pg:create --free
Setup the web endpoint
The newer versions of phoenix can quickly be deployed by setting the PHX_HOST
and PHX_SERVER
environment variables instead of editing the endpoint configuration.
For custom domains you will want to make further modifications.
gigalixir config:set PHX_HOST=${APP_NAME}.gigalixirapp.com
gigalixir config:set PHX_SERVER=true
Push to gigalixir and prosper
We are ready to deploy.
git push -u gigalixir main
You can monitor the deployment using gigalixir ps
. If you run into issues, check gigalixir logs
.
As always, if you hit any issues, we’re one email away to help. Just write us at Gigalixir Support.