Checklist For Migrating Your Rails Application

Engine Yard has done a lot of migrations — from other hosting providers to Engine Yard or from one AWS region to another. The steps are almost the same whatever the source and target environments are. You can think of migration as moving your Rails application from one set of servers to another.

The number 1 reason to migrate your Rails application is you want to change hosting providers. Another important reason is for disaster recovery as we mentioned here. Whatever your motivations are, make sure you follow the steps below.

Run Your Application on the Target Environment

This sounds like an obvious step but you’ll be surprised that some applications are migrated without testing everything. People think that because you’re using Linux in both environments, your app should work the same way. In theory, yes. But you don’t want to find out that one feature is broken during the migration. You want to catch the problem in the target environment before you even start.

Run the Rails app on the target environment. If you have background job workers, run those too.

Don’t Upgrade Unless Absolutely Necessary

It is tempting to perform upgrades on the target environment. If they’re not absolutely necessary, do those another time. You might think that Ruby, Nginx, database upgrades are harmless and they probably are. But you don’t want to have a lot of moving parts. If things go wrong, you want your list of possible suspects to be short.

Check Your Database Size

You can move your data from your source environment to your target environment using the dump and restore method (e.g. mysqldum or pg_dump). However, this results in longer downtime (hours or even days) for big databases.

Another approach is using replication. After replication has caught up, and when there’s no more data activity in the source environment, you can stop replication and start using the database in the target environment.

Copy All Static Files

Your database changes every day so you can’t actually move a final copy until the scheduled migration. For static files like images, copy them to the target environment before the migration. If these files are saved in your repository, you’re all set. If they are stored somewhere else, make sure you don’t forget to copy them.

Pre-warm the Database

You may have to pre-warm your database depending on your database queries and the database size. Your database internally uses caches because it’s faster to read from memory than disk. Before you generate a lot of traffic which results in database queries on the target environment, make sure it had the chance to cache most-used data. This can be done by simulating traffic to the target environment before the migration.

If you’re using AWS, you also want to pre-warm the EBS volumes. We create EBS volumes using snapshots that contain the data. The first time the files on the EBS volumes are accessed is slow because they’re copied from the snapshot. This is a one-time penalty on new EBS volumes. To avoid this, we take a backup (e.g. mysqldump or pg_dump) of the whole database to read all files on disk.

Perform a Dry Run

You have your app running on the target environment and you have pre-warmed your database. Time to migrate right? Not yet. Perform a dry run first. Go through all the steps for the actual migration. This gives you an idea on how long the migration is, possible issues, and most importantly, how long the site will be down.

You can skip some steps like putting up the maintenance page (see checklist below). During the dry run, you want your site to remain up and running.

Checklist

Here’s a checklist when doing the actual migration. You might have fewer or more steps depending on your actual setup.

• Lower the TTL of your DNS. Do this 2 days before or earlier.
• Put up a maintenance page on the source environment.
• Stop all processes that use the database (e.g. background jobs, cron jobs).
• Check that there are no writes happening in the database.
• Copy the database. Use the dump and restore method for small databases and replication for large databases.
• Test the target environment.
• Point your DNS to the target environment.

If different people are involved in the migration, put the name of the person on each item. This makes sure all steps are done and in the right order. More details is better. If you have to stop background jobs and cron jobs, you can put those in different lines. List the servers where the background jobs workers are running.

Free Migration Services

Engine Yard has a dedicated Migration Team. We will migrate your Rails application from your current hosting provider to Engine Yard. You’ll get 24/7 Stellar Support from Ruby DevOps experts, a Linux stack optimized for Ruby on Rails, and a platform that fully automates server provisioning and configuration. 

Yes! you want a safe migration.