Getting Started Guide¶
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.
Prerequisites¶
brew. For help, take a look at the homebrew documentation.git. For help, take a look at the git documentation.
python3.python2also works, but it is EOL as of January 1st, 2020.pip3. For help, take a look at the pip documentation.git. For help, take a look at the git documentation.
For example, run
sudo apt-get update
sudo apt-get install -y python3 python3-pip git-core curl
python3.python2also works, but it is EOL as of January 1st, 2020.pip3. For help, take a look at the pip documentation.git. For help, take a look at the git documentation.
Install the Command-Line Interface¶
Next, install the command-line interface. Gigalixir has a web interface at https://console.gigalixir.com/, but you will likely still want the CLI.
brew tap gigalixir/brew && brew install gigalixir
Warning
You may need to update Xcode command-line tools otherwise you might get an error like this
xcrun: error: invalid active developer path
To upgrade Xcode command-line tools, see https://stackoverflow.com/questions/52522565/git-is-not-working-after-macos-update-xcrun-error-invalid-active-developer-pa
pip3 install gigalixir --user
Make sure the executable is in your path, if it isn’t already.
echo 'export PATH=~/.local/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile
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")
Verify by running
gigalixir --help
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. Gigalixir’s free tier does not require a credit card, but you will be limited to 1 instance with 0.2GB of memory and 1 postgresql database limited to 10,000 rows.
gigalixir signup
Log In¶
Next, 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 without distillery or elixir releases.
For more information, click here: Modifying an Existing App to Run on Gigalixir.
Or if you just want to give gigalixir a spin, clone our reference app.
git clone https://github.com/gigalixir/gigalixir-getting-started.git
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¶
The default Elixir version is defined here which is quite old and it’s a good idea to use the same version in production as you use in development so let’s specify them. Supported Elixir and erlang versions can be found at https://github.com/HashNuke/heroku-buildpack-elixir#version-support
echo "elixir_version=1.11.3" > elixir_buildpack.config
echo "erlang_version=23.2" >> elixir_buildpack.config
Same for nodejs
echo "node_version=14.15.4" > phoenix_static_buildpack.config
If you are using Phoenix v1.6, there is also a mix assets.deploy alias in your mix.exs that you want to invoke post compilation:
echo 'hook_post_compile="mix assets.deploy && rm -f _build/esbuild"' >> elixir_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"
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¶
If you are not using releases, the easiest way to run migrations is as a job.
gigalixir run mix ecto.migrate
# this is run asynchronously as a job, so to see the progress, you need to run
gigalixir logs
If you are using distillery or Elixir releases, your app needs to be up and running, then run
# pg:migrate runs migrations from your app node so we need to add ssh keys first
gigalixir account:ssh_keys:add "$(cat ~/.ssh/id_rsa.pub)"
gigalixir ps:migrate
For more, see How to Run Migrations.