Run an app on fly.io

To run an app on fly.io you need four things: an account, the flyctl CLI, a Dockerfile, and two commands (fly launch and fly deploy). Fly takes your Docker image and runs it on small VMs close to your users.

First create an account on fly.io, then install flyctl on your system following fly.io/docs/hands-on/install-flyctl/. On macOS:

brew install flyctl

Then authenticate the CLI. This opens the browser to log you in:

fly auth login

Prepare the app

Go into your project folder and add a Dockerfile, if you don’t have one already. Fly deploys containers, so the Dockerfile describes how to build and start your app. Any app that runs in Docker runs on Fly, whatever the language.

What does fly launch do?

Now run:

fly launch

This command sets everything up. It looks at your project, asks a few questions (app name, region, whether you want a database), registers the app on your Fly account, and writes a fly.toml file in the project folder.

fly.toml is the app configuration. It stores the app name, the region, and the port your app listens on (internal_port, which is 8080 by default). Commit it to your repo. When you want to change how the app runs, you edit this file and deploy again.

Deploy

To ship the app, run:

fly deploy --ha=false

This builds the Docker image, pushes it, and starts the app. The --ha=false flag creates a single machine instead of two, which is what you want for a small hobby service. Every time you change the code, run fly deploy again.

Once it’s up, check it:

fly status
fly logs
fly open

fly status shows the machines and their state, fly logs streams the app output, and fly open opens the deployed app in your browser.

If your app needs environment variables, set them as secrets:

fly secrets set DATABASE_URL=postgres://...

The most common failure

The deploy succeeds but the app is unreachable, or health checks fail. Nine times out of ten the app is listening on localhost or on the wrong port.

Inside the VM, your app must listen on 0.0.0.0, and on the same port set as internal_port in fly.toml. Fix the listen address in your server code, match the port, deploy again, and check fly logs to confirm it started.