The goal of this guide is to get your app up and running on Gigalixir. You will sign up for an account, prepare your app, deploy, and provision a database.
If you’re deploying an open source project, we provide consulting services free of charge. Contact us and we’ll send you a pull request with everything you need to get started.
Install the Command-Line Interface
Gigalixir has a web interface at https://console.gigalixir.com/, but you will likely still want the CLI.
Install the CLI with:
curl https://get.gigalixir.com/cli | bash
When you get out of date, upgrade to the latest version by running the same command again:
curl https://get.gigalixir.com/cli | bash
If the command above isn’t an option in your environment (offline, air-gapped, or a read-only container), see the pip tab instead.
Install the CLI with:
irm https://get.gigalixir.com/cli.ps1 | iex
When you get out of date, upgrade to the latest version by running the same command again:
irm https://get.gigalixir.com/cli.ps1 | iex
Known limitations on Windows: gigalixir pg:psql fails at runtime, and
gigalixir ps:observer reports “not supported on this platform.”
If the command above isn’t an option in your environment (offline, air-gapped, or a read-only container), see the pip tab instead.
Works on macOS, Linux, and Windows. Use it only when the one-liner
installer above won’t work: an offline or air-gapped environment,
pip install --require-hashes, or a read-only container. pip fetches
the CLI binary the first time you run it, so it can’t finish that first
run in any of those environments.
Prerequisites:
macOS and Linux
pip3 install gigalixir --user
echo "export PATH=\$PATH:$(python3 -m site --user-base)/bin" >> ~/.profile
source ~/.profile
On Debian 12, Ubuntu 23.04 and newer, and other distributions where the
system Python is externally managed, this fails with
externally-managed-environment. Use your platform’s one-liner installer
instead.
Windows
pip3 install gigalixir --user
Make sure the executable is in your path, if it isn’t already.
On Windows Powershell, try something similar to this. Note this may vary based on your python version.
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\appdata\roaming\python\python38\Scripts", "Machine")
If you have any trouble, please reach out for help.
When you get out of date, upgrade to the latest version with:
pip3 install gigalixir --user --upgrade
Prerequisites:
Install the CLI with:
brew tap gigalixir/brew
brew install gigalixir/brew/gigalixir
brew tap takes a tap name, not a formula. The tap is gigalixir/brew,
and the formula is gigalixir/brew/gigalixir.
When you get out of date, upgrade to the latest version with:
brew update
brew upgrade gigalixir/brew/gigalixir
If brew upgrade reports success but the CLI doesn’t actually change, see
Homebrew upgrade reports success but does nothing.
You can verify installation by running:
gigalixir version
Create an Account
If you already have an account, skip this step.
Create an account using the following command. It will prompt you for your email address and password. You will have to confirm your email before continuing. All signups require a credit card; we place a temporary authorization hold to verify it. On the free tier the card is not linked to your account and is used only to prevent fraud and abuse — free tier usage is still free. You will be limited to 1 instance with 0.5GB of memory and 1 postgresql database limited to 10,000 rows.
gigalixir signup
Or if you want to use your Google account:
gigalixir signup:google
Log In
If you signed up with your Google account, you should already be logged in. Otherwise, log in. This will grant you an API key. It will also optionally modify your ~/.netrc file so that all future commands are authenticated.
gigalixir login
Verify by running:
gigalixir account
Prepare Your App
Most likely, there is nothing you need to do here and you can skip this step and “just deploy”, but it depends on what version of phoenix you’re running and whether you are okay running in mix mode or elixir releases.
For more information, see modifying an existing app.
Or if you just want to give Gigalixir a spin, clone our reference app.
git clone https://github.com/gigalixir/gigalixir-getting-started.git
Then just follow the instructions in the README under the Deploying section.
Set Up App for Deploys
To create your app, run the following command.
It will also set up a git remote. This must be run from within a git repository folder. An app name will be generated for you, but you can also optionally supply an
app name if you wish using
gigalixir create -n $APP_NAME. (There is currently no way to change your app name once it is created).
If you like, you can also choose which cloud provider and region using the
--cloud and --region options. We currently support gcp in
v2018-us-central1 or europe-west1 and aws in us-east-1 or us-west-2. The default
is v2018-us-central1 on gcp.
cd gigalixir-getting-started
APP_NAME=$(gigalixir create)
Verify that the app was created, by running:
gigalixir apps
Verify that a git remote was created by running:
git remote -v
If someone in your organization has already created the Gigalixir app and you only need to add the proper git remote to your local repository configuration, you can skip the app creation and add a the gigalixir git remote by using the git:remote command:
gigalixir git:remote $APP_NAME
Specify Versions
You must specify your Elixir and Erlang versions in an elixir_buildpack.config file. We recommend using the same versions in production as you use in development.
Supported Elixir and Erlang versions can be found at https://github.com/gigalixir/gigalixir-buildpack-elixir#version-support
Check your local versions with elixir --version and match them:
echo "elixir_version=1.17.3" > elixir_buildpack.config
echo "erlang_version=26.2.5" >> elixir_buildpack.config
If your app uses Node.js for asset compilation, specify that too:
echo "node_version=20.11.1" > phoenix_static_buildpack.config
Don’t forget to commit:
git add elixir_buildpack.config phoenix_static_buildpack.config
git commit -m "set elixir, erlang, and node version"
Phoenix v1.6 or greater uses esbuild to compile your assets but 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"
}
}
Don’t forget to commit:
git add assets/package.json
git commit -m "assets deploy script"
Provision a Database
Phoenix 1.4+ enforces the DATABASE_URL env var at compile time so let’s create a database first, before deploying.
gigalixir pg:create --free
Verify by running:
gigalixir pg
Once the database is created, verify your configuration includes a
DATABASE_URL by running:
gigalixir config
Deploy!
Finally, build and deploy.
git push gigalixir
Wait a minute or two for the app to pass health checks. You can check the status by running:
gigalixir ps
Once it’s healthy, verify it works:
curl https://$APP_NAME.gigalixirapp.com/
Or you could also run:
gigalixir open
Run Migrations
We try to make it easy by providing a special command. The command runs on your existing app container, so you’ll need to make sure your app is running first and set up your SSH keys.
gigalixir account:ssh_keys:add "$(cat ~/.ssh/id_rsa.pub)"
Then run:
gigalixir ps:migrate
For more, see How to Run Migrations..