Migrate

Migrate from Heroku

Moving a Heroku app to Stackap means turning the Procfile web process into a start script, copying config vars into environment variables, moving the Postgres data, and replacing each add-on.

Who this is for

No team has migrated from Heroku to Stackap yet. This guide maps concepts and lays out the steps, and it is not a record of a tested run.

The easiest Heroku apps to move are a single web process and a Postgres database. The hardest lean on worker dynos, a release phase and many add-ons, because each of those needs its own replacement.

Take inventory first

• The Procfile, line by line: web maps across, while worker, release and clock lines need a decision.
• Every config var, from heroku config for the app.
• Every add-on, from heroku addons, with what each one does for the app.
• The buildpack in use. Node and static apps are recognized, and anything else needs a Dockerfile.
• Scheduler jobs, and how often each runs.

What does not move automatically

Worker and release processes

A worker with no web port cannot run. A release phase that runs database migrations becomes a script you run before deploying, or a step at the app's start that is safe to repeat.

Add-ons

Each add-on is replaced one by one: Postgres by the project database, Scheduler by cron jobs, and logging, search, queues or email by a service you connect with its own variables.

Review apps and pipelines

There are none. Use a second project as staging.

The database copy

There is no self-serve database import yet. The operator loads your dump into the project's database with you, and the row counts are compared table by table afterwards.

How to know it worked

• Row counts match table by table.
• Every page and API route you rely on answers the same as on Heroku.
• Each scheduled job runs once.
• Anything that sends email or takes payments does so from one place only.

Going back

Keep the Heroku app until Stackap has carried real traffic. Going back is changing one DNS record.

Steps

1. Capture the data. Take a backup with heroku pg:backups:capture and download it with heroku pg:backups:download.
2. Create the project. Create a Stackap project and add its git remote.
3. Turn the Procfile into a start script. Put the web command in a start script in package.json, and make the app listen on PORT.
4. Set the environment. Set each config var with stackap env set.
5. Load the database. The operator restores the dump into the project database with you.
6. Deploy and compare. Push, read the build log, and compare pages with the live Heroku app.
7. Switch. Point your domain's DNS record at Stackap, then turn off Heroku's Scheduler jobs so none runs twice.

Early-access scope

• The database load is operator-assisted, not self-serve.
• Workers, release phases, pipelines and review apps have no equivalent.
• Non-Node apps need a Dockerfile, which is untested for most languages.
• No migration from Heroku has been run yet.

Questions

Last updated 2026-10-03.