Heroku CLI

Process

In this guide, sourceapp is the original (source) app and targetapp is the migrated (target) app.

Before beginning an app migration, please understand the proposed process as well as any nuances that are specific to your application. The following is the recommended migration approach.

Verification phase

Use heroku fork to create targetapp as a fork of sourceapp

Verify targetapp add-on provisioning and config vars.

Cut-over live traffic

Prepare DNS and data for migration

Put sourceapp in maintenance mode

Migrate production data

Move custom domains from sourceapp to targetapp

Adjust DNS settings to point to targetapp

Finalize targetapp setup

Fork application

Begin the verification phase by forking the application to create a copy in another region, for example the eu region. This will copy all Heroku Postgres data and config vars and will re-provision all add-ons. Depending on the size of your database this process may take some time.

Only Heroku Postgres data is automatically copied to the new application. All other add-ons are simply re-provisioned. Please consider the ramifications of this approach and plan for proper data migration with any other applicable add-ons.

Forking

heroku fork forks sourceapp to a new targetapp. targetapp should not exist prior to the fork command.

Re-run the fork command until it succeeds without error. Prior to each run make sure incomplete provisions of targetapp are destroyed.

$ heroku apps:destroy -a targetapp

Manual add-on configuration

There are some add-ons that require additional configuration after provisioning. There may be others beyond the add-ons listed below so please review your app’s add-ons for any that require manual configuration steps.

SSL Endpoint

Although the forking process re-provisions the SSL Endpoint on targetapp it does not migrate the required certs on your behalf. If your app uses SSL you need to add the original certs to your SSL endpoint instance on targetapp.

Scheduler

The Heroku Scheduler add-on requires that the job schedule be manually transferred. Open the scheduler dashboard for both sourceapp and targetapp side-by-side to view the diffs and manually copy the jobs.

Verification

Once forking has completed and all add-on configuration has been duplicated, open the forked application to verify it’s functioning properly before proceeding with the final migration steps.

$ heroku open -a targetapp

If your app uses OAuth, or any other domain-specific external service, you may have to provision a new service for use during this verification phase when the domain is not the same as your production setup.

Once your forked app has been verified to be functioning properly you can begin the cut-over process.

DNS preparation

Apps with custom domains should manually adjust their DNS settings as opposed to performing an app rename or using a DNS add-on. These alternatives are either not supported or incur non-trivial downtime.

If your app has custom domains, you should lower the TTL for each of them with your DNS provider to a low value, such as 60 or 120 seconds. This minimizes the
amount of downtime that results from changing your records during the migration process and allows you to quickly correct any DNS related errors.

To ensure that all DNS caches are updated with the new TTL, you should wait at least as long as the previous TTL before proceeding with the migration.

Database preparation

Although the app-forking process creates a new database, it’s only used to verify the new app’s setup. The actual database migration should occur only when the sourceapp is in maintenance mode (to avoid data being written during the migration) and should be done in a way that minimizes application downtime.

If you have a production tier database you can provision a follower in advance and wait until it is up-to-date with the master database before cutting over apps. (Development tier database users can bypass this step as their database migration will occur completely during the cut-over phase).

Create follower

Provision a new database (of the same plan) on targetapp to follow the current database on sourceapp.

After the follower has become available it may take some time for it to receive all the data from the source database. Use the pg:info command to view how many commits behind the follower is from the source database.

Only when the follower is, at most, a few hundred commits behind should you begin the application migration.

Maintenance mode

To ensure that no data modification occurs during the migration process, sourceapp should be put in maintenance mode.

From this point forward the source application will be inaccessible to your users. Only when the app has been migrated and all DNS propagation complete will the target app be accessible. Please plan for this downtime appropriately.

The follower database is now the primary database for targetapp and its location has been copied to the DATABASE_URL config var.

PG Backups

If you are using a hobby database (hobby-dev or hobby-basic) you will need to use PG Backups to transfer your database. You can use pg:copy to transfer the database directly:

$ heroku pg:copy sourceapp::DATABASE_URL DATABASE_URL -a targetapp

This process can take some time depending on the size of your database.

Add-on data

Other add-on providers may have a different procedure for migration, or no migration functionality at all. Whether the data needs to be migrated is a question of how you’re using that add-on. Please see the documentation for your add-on providers for more information.

Scale dynos

Using heroku ps to examine your dynos, copy the dyno formation from sourceapp to targetapp.

DNS

To route traffic to your new app, adjust the DNS settings so any custom domains resolve to targetapp. Add the following CNAME record in your DNS provider’s control panel.

Type

Name

Target

CNAME

www

targetapp.herokuapp.com

A-records are not supported. If required, use a DNS-level redirect or ALIAS record to resolve the root domain to targetapp.herokuapp.com.

SSL

If you’re using the SSL Endpoint add-on, no additional DNS configuration is required (this differs from the default region behavior, which requires using a domain like tokyo-123.herokussl.com). All traffic to www.example.com can now be served over SSL.

Propagation

If you’ve adjusted your DNS TTL to a low value it shouldn’t take more than a few minutes for requests to be routed to targetapp. Inspect the logs on targetapp to verify that requests are properly resolved and handled.

$ heroku logs -t -a targetapp

Once the DNS changes propagate all requests to your custom domain should be served by the new EU location.

Update git remotes

Forking your application doesn’t automatically create a new git remote in your current project. To deploy to targetapp you will need to establish the git remote yourself. Use heroku info to retrieve the Git URL of the new application and the set it manually.