Deploying on Gigalixir

View Source

What we'll need

The only thing we'll need for this guide is a working Phoenix application. For those of us who need a simple application to deploy, please follow the Up and Running guide.

Goals

Our main goal for this guide is to get a Phoenix application running on Gigalixir.

Steps

Let's separate this process into a few steps, so we can keep track of where we are.

  • Initialize Git repository
  • Install the Gigalixir CLI
  • Sign up for Gigalixir
  • Create and set up Gigalixir application
  • Provision a database
  • Make our project ready for Gigalixir
  • Deploy time!
  • Useful Gigalixir commands

Initializing Git repository

If you haven't already, we'll need to commit our files to git. We can do so by running the following commands in our project directory:

$ git init
$ git add .
$ git commit -m "Initial commit"

Installing the Gigalixir CLI

Follow the instructions here to install the command-line interface for your platform.

Signing up for Gigalixir

We can sign up for an account at gigalixir.com or with the CLI. Let's use the CLI.

$ gigalixir signup

# or with a Google account
$ gigalixir signup:google

Gigalixir’s free tier does not require a credit card and comes with 1 app instance and 1 PostgreSQL database for free, but please consider upgrading to a paid plan if you are running a production application.

Next, let's login

$ gigalixir login

# or with a Google account
$ gigalixir login:google

And verify

$ gigalixir account

Creating and setting up our Gigalixir application

There are two different ways to deploy a Phoenix app on Gigalixir: with mix or with Elixir's releases. In this guide, we'll be using Elixir's releases because it is the recommended way. For more information, see Elixir Releases vs Mix. If you want to deploy with the mix method, follow the Phoenix deploy with Mix Guide.

Creating a Gigalixir application

Let's create a Gigalixir application

$ gigalixir create -n "your-app-name"

Note: the app name cannot be changed afterwards. A random name is used if you do not provide one.

Specifying versions

Gigalixir requires that you specify the Erlang and Elixir versions you intend to use. It's generally a good idea to run the same version in production as you do in development. For example:

$ echo 'elixir_version=1.17.2' > elixir_buildpack.config
$ echo 'erlang_version=27.0' >> elixir_buildpack.config
$ git add elixir_buildpack.config

Gigalixir will use the latest nodejs version if you do not specify a version. If you want to specify your nodejs version, you can do so like this:

$ echo 'node_version=22.7.0' > phoenix_static_buildpack.config
$ git add elixir_buildpack.config phoenix_static_buildpack.config assets/package.json

Finally, don't forget to commit:

$ git commit -m "Set versions"

Provisioning a database

Let's provision a database for our app. For a free database, run the following command

$ gigalixir pg:create --free

For a production ready database, be sure to upgrade your account to the Standard Tier and create a Standard tier database

$ gigalixir account:upgrade
$ gigalixir pg:create

Verify the database was created

$ gigalixir pg

Verify that a DATABASE_URL and POOL_SIZE were created

$ gigalixir config

Making our Project ready for Gigalixir

There's nothing we need to do to get our app running on Gigalixir, but for a production app, you probably want to enforce SSL.

Force HTTPS/SSL Connections

To do that, see Force SSL

Database Connection Security

You may also want to use SSL for your database connection.

For a free tier database, update your Repo config with:

ssl: true,
ssl_opts: [
  verify: :verify_none,
  cacerts: :public_key.cacerts_get()
]

For a production database, use this instead:

ssl: true,
allowed_tls_versions: [:"tlsv1.2"],
ssl_opts: [verify: :verify_none]

Deploy Time!

Our project is now ready to be deployed on Gigalixir. Be sure you have everything committed to git and run the following command:

$ git push gigalixir

Check the status of your deploy and wait until the app is Healthy

$ gigalixir ps

Run migrations

$ gigalixir ps:migrate

Check your app logs

$ gigalixir logs

If everything looks good, let's take a look at your app running on Gigalixir

$ gigalixir open

Useful Gigalixir Commands

Open a remote console

$ gigalixir account:ssh_keys:add "$(cat ~/.ssh/id_rsa.pub)"
$ gigalixir ps:remote_console

To set up clustering, see Clustering Nodes

For custom domains, scaling, jobs and other features, see the Gigalixir Documentation.

Troubleshooting

See Troubleshooting and the FAQ

Also, don't hesitate to email help@gigalixir.com or request an invitation and join the #gigalixir channel on Slack.