Documentation Frameworks and migration

Migrate from Heroku

Map dynos, the Procfile, config vars, Postgres, workers and Scheduler to Gregale, step by step.

~3 min read
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

HerokuGregale
AppApp, deployed with gregale deploy
DynoInstance: a Firecracker microVM per instance. Idle apps park and wake on the next request.
BuildpacksSource 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 dynoA background worker service in a project: a service without ports: runs all the time
Config varsSecrets (gregale env set) and environment variables
Heroku PostgresManaged PostgreSQL, bound to the app as DATABASE_URL
Heroku SchedulerCrons, which call a path on your app on a schedule
Review appsPreview environments
Custom domains and ACMCustom domains
heroku logs --tailgregale logs my-api (Logs)
heroku releases:rollbackgregale rollback my-api --to v41 (Safe releases)

Before you start

  • The app must listen on 0.0.0.0 and the PORT environment 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 DYNO variable stay off on Gregale. Heroku's own getting-started apps open ALLOWED_HOSTS, the database and HTTPS settings only when DYNO is set; key them on a variable you set with gregale env set instead.
  • Heroku's buildpacks do work at build time that Gregale does not: Django's collectstatic (run it when the app starts, into a writable STATIC_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:

bash
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:

bash
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

bash
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:

bash
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_URL in heroku.env. Apps reach outside hosts on ports 80 and 443 only, so on Pro and Scale open the database port first with gregale 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_URL
    

    Restore a pg_dump of 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 at MIGRATION_DATABASE_URL, the credential that can change the schema. DATABASE_URL goes 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 without ports: 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