Migrating an Application to Heroku Europe

Last Updated: 24 March 2014

europe migrate regions

Table of Contents

This article describes a beta feature. Functionality may change prior to general availability.

Follow the steps outlined in this article to copy all add-on services, config vars, and Heroku Postgres data to a new app in the EU region and migrate live traffic to the new app.

Heroku Toolbelt

You must have the Heroku Toolbelt installed to use the features described here. Verify your toolbelt installation and update it to the latest version with heroku update.

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 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.

$ heroku fork -a sourceapp targetapp --region eu
Creating fork targetapp... done
Copying slug... done
Adding pgbackups:plus... done
Adding heroku-postgresql:dev... done
Creating database backup from sourceapp... .. done
Restoring database backup to targeteapp... .. done
Copying config vars... done
Fork complete, view it at http://targetapp.herokuapp.com/

Provision failures

When forking to a different region than sourceapp some add-ons may fail provisioning if they’re not available in the new region or are outdated plans.

$ heroku fork -a sourceapp targetapp --region eu
Creating fork targetapp... done
Copying slug... ........ done
Adding airbrake:developer... done
Adding bonsai:test... skipped (not found)
Adding komrade:test... skipped (This app is in region eu, komrade:test is only available region us)
...

If the add-ons can’t be provisioned because the original plan no longer exists, upgrade the plan on the source app to ensure a seamless migration.

$ heroku addons:upgrade memcachier:dev -a sourceapp
Upgrading to memcachier:dev on sourceapp... done, v207 (free)

If the add-on is not yet available in the new region consider using another provider of that service that does have availability in your app’s region.

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.

$ heroku certs:add server.crt server.key -a targetapp
Resolving trust chain... done
Adding SSL Endpoint to targetapp... done
targetapp now served by targetapp.herokuapp.com

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.

$ heroku addons:open scheduler -a sourceapp
$ heroku addons:open scheduler -a targetapp

Verification

Once forking has completed and all add-on configuration has been duplicated, open the forked application to verify its functioning 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 db 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.

$ heroku addons:add heroku-postgresql:crane -a targetapp --follow `heroku config:get DATABASE_URL -a sourceapp`
Adding heroku-postgresql:crane on targetapp... done, v32 ($50/mo)
Attached as HEROKU_POSTGRESQL_CHARCOAL_URL
Follower will become available for read-only queries when up-to-date
Use `heroku pg:wait` to track status.

$ heroku pg:wait -a targetapp
Waiting for database HEROKU_POSTGRESQL_CHARCOAL_URL... / available

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.

$ heroku pg:info -a targetapp
=== HEROKU_POSTGRESQL_CHARCOAL_URL
Plan:        Crane
Status:      available
Region:      eu-west-1
...
Behind By:   47980 commits

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.

$ heroku maintenance:on -a sourceapp
Enabling maintenance mode for sourceapp... done

Switchover database

With the sourceapp in maintenance mode it’s now safe to migrate data to targetapp. The approach you take here depends on your Heroku Postgres database tier.

Production tier database

If you have a production tier database and have created a follower database on targetapp, wait until it is fully caught up (0 commits behind) and promote it to be the master.

$ heroku pg:info -a targetapp
=== HEROKU_POSTGRESQL_CHARCOAL_URL
Plan:        Crane
Status:      available
Location:    eu-west-1
...
Behind By:   0 commits

$ heroku pg:unfollow -a targetapp HEROKU_POSTGRESQL_CHARCOAL_URL
Unfollowing HEROKU_POSTGRESQL_CHARCOAL_URL... done

$ heroku pg:promote -a targetapp HEROKU_POSTGRESQL_CHARCOAL_URL
Promoting HEROKU_POSTGRESQL_CHARCOAL_URL to DATABASE_URL... done

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

PG Backups

Only if you do not have a follower established or are using a development database (dev or basic) will you need to use PG Backups to create and transfer a database backup.

Make sure both apps have the PG Backups add-on:

$ heroku addons:add pgbackups -a sourceapp
$ heroku addons:add pgbackups -a targetapp

Capture a backup of the sourceapp database:

$ heroku pgbackups:capture -a sourceapp

And import it into targetapp:

$ heroku pgbackups:restore -a targetapp `heroku pgbackups:url -a sourceapp`

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.

$ heroku ps -a sourceapp
=== web: `bundle exec thin start -p $PORT`
web.1: up 2013/02/12 18:56:17 (~ 20h ago)
web.2: up 2013/02/12 19:14:45 (~ 19h ago)

$ heroku scale web=2 -a targetapp

Check your logs to ensure the dynos started properly.

$ heroku logs -t -n 1000 -a targetapp

Custom domains

For targetapp to receive user activity, Heroku must know which domain is served by your app. List the custom domains on the old app:

$ heroku domains -a sourceapp
=== sourceapp Domain Names
www.example.com

For each of these domains, remove them from the sourceapp and add them to targetapp.

$ heroku domains:remove -a sourceapp www.example.com
Removing www.example.com from sourceapp... done

$ heroku domains:add -a targetapp www.example.com
Adding www.example.com to targetapp... done

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.

<table>
  <tr>
    <th>Type</th>
    <th>Name</th>
    <th>Target</th>
  </tr>
  <tr>
    <td>CNAME</td>
    <td>www</td>
    <td>targetapp.herokuapp.com</td>
  </tr>
</table>

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.

$ heroku info -a targetapp
=== targetapp
...
Git URL:       git@heroku.com:targetapp.git
...

$ git remote add forked git@heroku.com:targetapp.git

In this example, targetapp’s git remote is named forked. Deploy to this app with:

$ git push forked master

If you wish to make the new app the default deployment target (after migration) you can rename the git remotes.

$ git remote rename heroku old
$ git remote rename forked heroku

targetapp is now the default deployment target for all future deploys. After a reasonable period of time, be sure to de-provision any unused resources on sourceapp.

Forked app state

Forked apps are as close to the source app as possible. However, there are some differences.

Collaborators

No users from the source app are transferred over to the forked app. You need to add collaborators yourself.

$ heroku sharing:add colleague@example.com -a targetapp

Labs features

Any enabled Heroku Labs features on sourceapp are not re-enabled on targetapp. You will need to re-enable these yourself.