Migrate from Heroku
Map dynos, the Procfile, config vars, Postgres, workers and Scheduler to Gregale, step by step.
On this page
A Heroku app usually moves to Gregale without code changes: Gregale reads the
same Procfile, builds from source without a Dockerfile, and passes
configuration as environment variables. This page maps Heroku's pieces to
Gregale's and walks through a move.
How Heroku maps to Gregale
| Heroku | Gregale |
|---|---|
| App | App, deployed with gregale deploy |
| Dyno | Instance: a Firecracker microVM per instance. Idle apps park and wake on the next request. |
| Buildpacks | Source builds detect Node, Python and Go (Deploy a web framework), or use your Dockerfile |
Procfile web: | Read as is: it is the app's start command |
Procfile release: | Read as is: a release command that runs before the new version takes traffic |
worker dyno | A background worker service in a project: a service without ports: runs all the time |
| Config vars | Secrets (gregale env set) and environment variables |
| Heroku Postgres | Managed PostgreSQL, bound to the app as DATABASE_URL |
| Heroku Scheduler | Crons, which call a path on your app on a schedule |
| Review apps | Preview environments |
| Custom domains and ACM | Custom domains |
heroku logs --tail | gregale logs my-api (Logs) |
heroku releases:rollback | gregale rollback my-api --to v41 (Safe releases) |
Before you start
- The app must listen on
0.0.0.0and thePORTenvironment variable, as it already does on Heroku. web:must start a production server (Gunicorn, Uvicorn,node), not a development one.- Settings that switch on Heroku's
DYNOvariable stay off on Gregale. Heroku's own getting-started apps openALLOWED_HOSTS, the database and HTTPS settings only whenDYNOis set; key them on a variable you set withgregale env setinstead. - Heroku's buildpacks do work at build time that Gregale does not: Django's
collectstatic(run it when the app starts, into a writableSTATIC_ROOT; see Deploy a Django app), and a Go binary named after the app (start./out; see Deploy a Go app). - Keep the Heroku app running until the Gregale one serves real traffic.
Check what Gregale detects, from the repository root:
gregale deploy --dry-run
1. Copy the configuration
Export the config vars as KEY=VALUE lines. --secrets-file takes each
value exactly as written, so export JSON and convert it rather than using
heroku config --shell, which quotes some values:
heroku config --json --app my-heroku-app \
| jq -r 'to_entries[] | "\(.key)=\(.value)"' > heroku.env
Remove the lines you will not use on Gregale (for example DATABASE_URL if
you move to managed PostgreSQL). Values that span several lines do not fit
this format; set those with gregale env set after the first deploy.
2. Deploy
gregale deploy --name my-api --secrets-file heroku.env
rm heroku.env
The values are sealed before the first deployment starts. The deploy prints the app's URL when it is live. If it fails:
gregale app health my-api --errors
gregale logs my-api
3. The database
Gregale has no one-step import from Heroku Postgres. Two ways to move:
-
Keep Heroku Postgres for now. Leave
DATABASE_URLinheroku.env. Apps reach outside hosts on ports 80 and 443 only, so on Pro and Scale open the database port first withgregale app egress-ports add my-api 5432; see Networking. -
Move to managed PostgreSQL. Create a database and bind it:
bash gregale add postgres --app my-api --region <region> gregale postgres attach my-api-postgres my-api --access migration --env MIGRATION_DATABASE_URLRestore a
pg_dumpof the Heroku database with your usual PostgreSQL tools through Connect from your laptop (it needs app tasks on your plan), then point the app's migrations atMIGRATION_DATABASE_URL, the credential that can change the schema.DATABASE_URLgoes through a connection pooler in transaction mode; see Managed PostgreSQL for what that changes.
4. Workers and scheduled jobs
- A
worker:process becomes a background worker service. Describe the web and worker processes in a Compose file and deploy it as a project; a service withoutports:runs all the time. - Heroku Scheduler tasks become crons. A cron calls an HTTP path on your app, so expose each task as a route your app protects.
5. Switch traffic
Add your domain to the Gregale app and verify it as Custom domains describes, then move DNS. When the Gregale app has served traffic for a while, scale the Heroku dynos to zero and remove the Heroku app.
Spotted a problem on this page? Tell us