Deploying on Fly.io

Deploying on Fly.io

Step by step description of the process from deciding to deploy an app on Fly.io and to having a deployed app, alongside an explanation on setting up CI/CD using Github actions.

Content

• Installing flyctl
• Launching on Fly.io
  • Secrets
  • fly.toml
• Continuous deployment on Fly.io
  • Get a fly token
  • Github actions
  • fly.yml
• More relevant documentation

---

Installing flyctl

In order to deploy apps on Fly.io you're going to need to install their commandline utility.
For example on Windows you'd open the PowerShell commandline and run:

pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

For other operating systems you can check their documentation here: Install flyctl.
Make sure to register on Fly.io and login into your account in the commandline.

Launching on Fly.io

Note

If you prefer, you can follow Fly.io's documentation of the process instead: Create an app with Fly Launch, then skip to the fly.toml section.

1. Select or create a Dockerfile and .dockerignore that fit your app, and add them to the root of your project.
2. Run the following command in a terminal to create the app on Fly.io and deploy it in one go:

fly launch

Alternatively if you'd like to check your configuration before you deploy, you can run:

fly launch --no-deploy

3. Fill out the information in the terminal and you're all set!

Warning

Currently fly apps get initialized with 2 machines, which doesn't fit all types of apps (and can cost more).
To switch to a single machine run fly scale 1.

Secrets

When deploying an app, it's recommended to store sensitive information such as tokens, passwords and so on as Environment variables.
In the case of Fly.io and many hosting services - those Environment variables are called Secrets.

You can set your secrets one by one using the following command, while VARNAME is the name of the variable, and VARVALUE is its value:

fly secrets set VARNAME=VARVALUE

Note

Fly.io seems to be adding more options to their web interface and it's now possible to set new environment variables in the Secrets tab inside the app's page.

fly.toml

This configuration file gets generated by fly when you launch a new app, but sometimes it doesn't fit the app you'd like to deploy so you'll need to make adjustments to it.
The attached fly.toml file is one I use for Node JS apps with a web interface, these configurations tell Fly.io to:

• Use Dockerfile and .dockerignore files to build the app.

[build]
  dockerfile = "Dockerfile"
  ignorefile = "dockerignore"

Tip

While you're free to build using images - I find that using Node JS images for launching on Fly.io uses more ram than I can afford, and at some points wouldn't launch at all... so I'd recommend using a Dockerfile as once you set one up it's pretty hassle free.

• Open port 8080 - meaning that when the app launches it listens to post 8080, can be changed to whichever port the app listens to.

[[services]]
  ...
  internal_port = 8080

• Give the app 1 minute of grace period - fly waits for a minute to let the app fully launch before preforming checks on the app, can be adjusted for faster apps.

[[services]]
  ...
  [[services.tcp_checks]]
    ...
    grace_period = "1m0s"

• Uses a swap size of 512mb, adjust based on your needs or remove completely if not using memory swap.

swap_size_mb = 512

For these configurations to work, I also have the following in my package.json:

  "dockerfile": {
    "port": 8080,
    "swap": "512M"
  }

Important

If you're using a Dockerfile that relies on package-lock.json, make sure to remove the file from your .dockerignore and .gitignore as launching will fail otherwise.

Continuous deployment on Fly.io

Note

You can follow the official documentation of the process: Continuous Deployment with Fly.io and GitHub Actions, then skip to the fly.yml section.

Get a fly token

1. Assuming you already have the app on Fly.io - simply run the following:

fly tokens create deploy -x 999999h

The output you get is your app's token and will be needed in a moment, make sure to keep it secret as it's essentially a "password" for your app.

Github actions

1. Go to the settings of your repository.
2. Open Secrets and variables on the side bar and go to Actions.
3. Click New repository secret:
   • Name the secret, we're going to follow the guide and call it FLY_API_TOKEN.
   • Paste the token you got from fly into the Secret section.

fly.yml

1. Create a folder in the root of your project called .github.
2. Inside .github create another folder called workflows.
3. Place fly.yml inside of workflows.
   • If you'd like your Github repository to automatically update the Environment it's running (in the Deployments section), add the following lines in fly.yml under the deploy category, while APPNAME is the name you want the Environment to have, and APPURL is the app's url (if it has one):

deploy:
  ...
  environment:
    name: APPNAME
    url: APPURL
steps:
  ...

Now when you push your code to Github (or create a new Release) the app will automatically redeploy on fly.

Tip

If you'd like the app to only redeploy on pushes to main/master feel free to adjust the on action in the fly.yml file to list the exact branch (like in fly's documentation), or alternatively push your code to main/master then add .github to your .gitignore so the folder won't get pushed to other branches.

More relevant documentation

Environment variables

• How to read environment variables from Node.js
• dotenv module

Fly.io

• Get app info
• Deploy an app - fly deploy (redeploy an app you already launched, updates its code)
• Restart apps or Machines - fly apps restart APPNAME/fly machine restart MACHINEID (restart the app without changing its code)
• Set secrets
• Scale Machine CPU and RAM
• Grace period
• Delete an app - fly apps destroy APPNAME

Github

• Understanding GitHub Actions
• Using secrets in Github Actions