Deploying on Gigalixir
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 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
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
And verify
$ gigalixir account
Creating and setting up our Gigalixir application
There are three different ways to deploy a Phoenix app on Gigalixir: with mix, with Elixir's releases, or with Distillery. In this guide, we'll be using Mix because it is the easiest to get up and running, but you won't be able to connect a remote observer or hot upgrade. For more information, see Mix vs Distillery vs Elixir Releases. If you want to deploy with another method, follow the Getting Started 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.
Verify the app was created
$ gigalixir apps
Verify that a git remote was created
$ git remote -v
Specifying versions
The buildpacks we use default to Elixir, Erlang, and Node.js versions that are quite old and it's generally a good idea to run the same version in production as you do in development, so let's do that.
$ echo 'elixir_version=1.10.3' > elixir_buildpack.config
$ echo 'erlang_version=22.3' >> elixir_buildpack.config
$ echo 'node_version=12.16.3' > phoenix_static_buildpack.config
Phoenix v1.6 uses esbuild
to compile your assets but all Gigalixir images come with npm
, so we will configure npm
directly to deploy our assets. Add a assets/package.json
file if you don't have any with the following:
{
"scripts": {
"deploy": "cd .. && mix assets.deploy && rm -f _build/esbuild"
}
}
Finally don't forget to commit:
$ git add elixir_buildpack.config phoenix_static_buildpack.config assets/package.json
$ git commit -m "Set Elixir, Erlang, and Node version"
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. To do that, see Force SSL
You may also want to use SSL for your database connection. For that, uncomment the line ssl: true
in your Repo
config.
Provisioning a database
Let's provision a database for our app
$ gigalixir pg:create --free
Verify the database was created
$ gigalixir pg
Verify that a DATABASE_URL
and POOL_SIZE
were created
$ gigalixir config
Deploy Time!
Our project is now ready to be deployed on Gigalixir.
$ git push gigalixir
Check the status of your deploy and wait until the app is Healthy
$ gigalixir ps
Run migrations
$ gigalixir run mix ecto.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 open a remote observer, see Remote Observer
To set up clustering, see Clustering Nodes
To hot upgrade, see Hot Upgrades
For custom domains, scaling, jobs and other features, see the Gigalixir Documentation
Troubleshooting
See Troubleshooting
Also, don't hesitate to email help@gigalixir.com or request an invitation and join the #gigalixir channel on Slack.