
- Web apps in any language (Node.js, Python, Ruby, Go, etc.)
- Postgres databases
- Redis
- Background workers
- Environment variables
- Custom domains
TL;DR - The Fast Path
For experienced developers, here’s the entire migration in 7 commands:Prerequisites
Install both CLIs:Step 1: Export Your Heroku Configuration
First, let’s capture everything about your Heroku app.- Your add-ons (Postgres, Redis, etc.)
- Your dyno types (web, worker, etc.)
Step 2: Prepare Your App
Make sure you have your app’s source code locally:Check for a Dockerfile
Fly works best with a Dockerfile. If you don’t have one, that’s fine -fly launch will generate one for you based on your app type.
Check your Procfile
Your HerokuProcfile maps directly to Fly processes. A typical Procfile:
Step 3: Launch on Fly
From your app directory:- Detect your app type (Node, Python, Rails, etc.)
- Generate a Dockerfile if needed
- Create a
fly.tomlconfiguration file - Ask if you want to provision a Postgres database
- Choose a name for your app (or accept the generated one)
- Select your preferred region
- Say Yes to Postgres if you need a database (choose “Managed Postgres” for the fully-managed option)
- Say No to deploy now - we’ll do that after setting up secrets
Step 4: Set Up Your Database
If you have Heroku Postgres, create a Managed Postgres cluster on Fly:CLUSTER_ID part) - you’ll need it for the next few commands. If you lose it, you can always find it with fly mpg list.
To import your data, dump it from Heroku with pg_dump, then restore it with fly mpg connect, which opens a tunnel to your database and runs psql for you:
pg_dump finishes without an error before you restore: a dump that failed partway can restore without complaint. The restore prints a few query results, such as setval, and carries on past errors. You’ll see errors about the pg_stat_statements extension and about Heroku’s own event triggers, like these:
pg_dump is version 17 or later and your cluster runs Postgres 16, you’ll also see unrecognized configuration parameter "transaction_timeout", which is safe to ignore too.
Read any other error before you go on: it means a statement didn’t run. If the output ends with connection to server was lost and Error: exit status 2, the connection dropped partway and the import isn’t complete. Don’t run the restore again on the same database, because tables that already loaded would get their rows twice. Create an empty database with fly mpg databases create CLUSTER_ID --name heroku_import, then add --database heroku_import before the -- in the restore command, and to fly mpg attach below. See Restore errors.
Attach the database to your app:
DATABASE_URL as a secret on your app.
Step 5: Set Up Redis (if needed)
If you use Heroku Redis or Redis Cloud:Step 6: Import Environment Variables
Remember thatheroku-env.txt file we created? Let’s import it:
Step 7: Configure Processes (Web + Workers)
If your app has multiple process types (web + worker), edit yourfly.toml:
Step 8: Deploy
Step 9: Verify Your App
Step 10: Migrate Your Domain
If you have a custom domain on Heroku:- For apex domains (example.com): Create an A record pointing to the IPv4 address
- For subdomains (www.example.com): Create a CNAME pointing to
your-app-name.fly.dev
Quick Reference: Command Mapping
Common Add-on Replacements
Multiple Environments (Staging/Production)
Fly doesn’t have “pipelines” like Heroku. Instead, create separate apps:Shutting Down Heroku
Once everything is working on Fly:- Update your DNS to point to Fly
- Wait for DNS propagation (check with
dig yourdomain.com) - Monitor both apps for a day to ensure no traffic goes to Heroku
- Scale down Heroku dynos:
heroku ps:scale web=0 worker=0 -a $HEROKU_APP - Cancel Heroku add-ons
- Delete the Heroku app:
heroku apps:destroy -a $HEROKU_APP