Migrating Your Drupal 8 Site to Acquia Cloud Platform Hosting

September 1, 2020 | Matthew Ramir
Migrating site to Acquia Cloud Platform image

Moving between hosting providers is never an easy task, but it can be done in a way that doesn’t have to be painful. One of our clients recently recognized the value of a hosting provider like Acquia. We were tasked with moving their site from custom AWS hosting to the Acquia Cloud Platform.

Acquia is the only Drupal hosting platform that's built for Drupal developers by Drupal developers. Acquia Cloud Platform is also the only web hosting solution for Drupal designed to scale to meet the demands of enterprise-class business challenges. With Drupal managed hosting from Acquia, you can create, scale, and manage your digital experiences knowing you’re leveraging the best that Drupal has to offer.

Acquia Cloud Platform provides secure and compliant web hosting for Drupal that delivers everything your teams need to build and manage Drupal-based digital experiences, including fully managed Drupal hosting, robust development tools, enterprise-grade security, and world-class support.

When migrating your site to a new platform, we want to ensure we’re still following best practices. There are many caveats to moving websites between hosting providers that can arise. We will discuss a few common ones throughout this article; however, every situation is unique. This means that your migration should be well documented, predictable, and repeatable. You should expect to perform the steps multiple times as these issues are uncovered and resolved. If we follow best practices and develop iteratively, we can prevent problems from making it to our live site.


Our first step is to evaluate the codebase and make sure it is following best practices for Drupal development. This includes things like ensuring we are properly using version control, dependency management, and the config system. Most Drupal 8 sites should already be using these basic concepts, but this is a great point to perform some basic checks.

Next, we want to prepare the codebase to take advantage of all of Acquia Cloud Platform’s features. At the very least, we will want the Acquia Connector module which will allow our site to send metrics and other data to the Acquia subscription. This gives us access to tools like Insights and also helps Acquia maximize uptime. Another module we want to install is Acquia Purge for clearing varnish as well as the Cloud Platform CDN.

Once our code is ready, we need to get the code into Acquia’s repository so that we can deploy it to our new pre-production environment. This is a great opportunity to evaluate our CI/CD pipeline and make adjustments that aligned us with best practices. Fortunately, this project was already based on Acquia’s Build and Launch Tool (BLT), which gave us a plethora of commands to easily plug into our CI system. Using BLT also meant pushing the code was simple as changing the git.remotes configuration setting and running the artifact:deploy command. 


With our codebase in place, it’s time to get the fun started and transfer the database to the new environment. Using our friendly neighborhood Drush CLI Tool, backing up and restoring the database is extremely easy. To use Drush, we need to download aliases that are conveniently provided under the credentials tab within our Acquia account settings. The aliases are simply dropped into the drush/sites directory within our codebase.

To create a backup of the database we use the following command:

drush @client_legacy.prod sql:dump \
     --result-file /tmp/client.sql --gzip \  

The results-file parameter tells Drush to store the file in a consistent place. This helps us maintain that predictability and consistency that is so crucial to our success. We also want to make sure we’re passing the gzip flag to compress the resulting backup file. It is important to note that this flag will add .gz to the end of your results-file path. Thus our resulting backup is actually located at /tmp/client.sql.gz.

The structured-tables-list option tells Drush to skip backing up the data for any tables matching the list. In the case of Drupal, we can safely ignore any cache as well as any module-specific tables that are generated dynamically or do not need to be preserved. This is extremely helpful in cutting down on database backup sizes. 

Once the database backup has been created, we need to transfer it to the Acquia server. There are many ways to accomplish this, and my preference is to use sftp or scp. This is also a good point to take some notes on how long the transfer takes!

sftp user@client.legacy.prod 
sftp> get /tmp/client.sql.gz
    # /tmp/client.sql.gz. 100%  500MB   4.2MB/s   02:00

sftp client.prod@client.ssh.prod.acquia-sites.com
sftp> put client.sql.gz
    # /tmp/client.sql.gz. 100%  500MB   2.1MB/s   04:00

Our last step with the database is to import it into the Acquia site. One significant problem with this migration in particular was that the client’s database backup was roughly 2GB when uncompressed. Importing a larger database can present many problems such as the server running out of resources or the ssh connection timing out. Our solution for these issues was to run the import process as a fork and monitor the server until the import finished. To minimize the problem surface, we ran each command in an atomic way—avoiding unix pipes and logic where possible. This made our lives easier as we debugged the issue we encountered.

The commands we ran to import the database were as follows:

drush @client.prod ssh --ssh-options="-o ServerAliveInterval=60"# SSH into acquia server
    cd ~ # Go to default upload location
    rm -f client.sql # Remove any existing unzipped backups
    gunzip client.sql.gz # Unzip our backup
    cd /var/www/html/client.prod # Navigate back to our codebase.
    drush sql-drop # Delete any existing 
    drush sqlc < ~/client.sql & # Import the database
    free -h; ps -aux; top; # etc... Wait for database import to complete

At this point, we should be able to visit our temporary Acquia production URL and see a version of our site without any images.


The next step in the migration is to sync the files which is easily achievable via the Drush rsync command. However, to keep in the spirit of optimization, we grabbed the rsync command executed by Drush and added a couple of options to make it more performant. This was especially helpful as the client had dozens of gigs worth of files.

The rsync command we used to sync the files were as follows:

rsync -e 'ssh ' -akzv --ignore-existing \
    --exclude "styles" --stats --progress \
    /efsmount/client.com/files/  \

The ignore-existing flag tells rsync skip copying files that already exist, which is helpful if your files tend not to be changed. We also want to exclude the styles directory as it can be dynamically generated (similar to cache tables). 

Test and Launch!

Now that you have your complete site copied over, you can begin testing and validate that the site was properly copied. As issues are uncovered in QA and UAT, you will likely want to recopy the database and files to your Acquia Cloud Platform. Good thing we clearly documented our steps! Client data constantly changes and we want to do our best to ensure the success of our migration.

Once your site is stable and has been thoroughly tested on Acquia, it’s time to launch! Using the timings from our notes we can work with the client to schedule a maintenance period. It’s during this period that we will perform one final migration before cutting over our DNS. On launch day, we review our documentation with the entire team to ensure all members of the team (including the client) are on the same page. 

As the work begins, you should be able to copy and paste all commands that you need to run and easily notify your team as you progress through the steps. Once your migration is complete, all that's left is to flip the DNS and decommission our old servers. Congratulations on your new Acquia Cloud Platform site!