The following instructions allow a user to go from zero to hero with Gigalixir, Phoenix, and Mix. This guide uses the latest versions:

Last updated/tested on 2025-05-09.

Gigalixir recommends using Elixir Releases for the startup and runtime efficiency.

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 27.3.4
asdf install elixir 1.18.3-otp-27
asdf install nodejs 24.0.1

Now set the versions as active.

asdf set erlang 27.3.4
asdf set elixir 1.18.3-otp-27
asdf set nodejs 24.0.1
# For asdf < 0.16, use `asdf local` instead of `asdf set`

Install Phoenix Framework

Install hex

mix local.hex

Get the latest version of Phoenix and install it.

mix archive.install hex phx_new

Create a new phoenix application

Create the phoenix application, in this case mix_example is the name of the application. You will probably want use some other name.

mix phx.new mix_example --install

Now move into the new project directory and make it a git repository.

cd mix_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. By default the buildpacks support a .tool-versions file which asdf generates. Let’s create the file and add it to git.

asdf set erlang 27.3.4
asdf set elixir 1.18.3-otp-27
asdf set nodejs 24.0.1
# For asdf < 0.16, use `asdf local` instead of `asdf set`

git add -f .tool-versions
git commit -m "set elixir, erlang, and node version"

Not using ASDF? You can create the .tool-versions file manually with this format.

Use Mix instead of Elixir Releases

The gigalixir-24 stack will default to Elixir Releases for the build process. We need to tell Gigalixir to use Mix instead.

mkdir -p .gigalixir
touch .gigalixir/mix
git add .gigalixir/mix
git commit -m "use a mix build"

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].

gigalixir create
gigalixir pg:create --free

If you created your app in our console, you can link it to your local git repository with gigalixir git:remote APP_NAME.

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.

NEXT ⟶