Documentation

Migrating an Existing Project to Servd

In this guide, we're going to help you migrate your existing Craft CMS site over to Servd. The main steps we'll be covering include:

  1. Preparing your DNS TTLs
  2. Connecting your Craft CMS codebase
  3. Configuring your front-end build pipeline
  4. Importing your database data
  5. Uploading your local volume assets
  6. Preparing your production environment
  7. Going live

When you create a new trial project on Servd, you instantly get access to a staging server. We'll be using it to get everything configured correctly, before pushing the site live to the production server.

1. Preparing your DNS TTLs #

If your site uses a reverse proxy service, such as Cloudflare, you should be able to skip this step as your DNS records shouldn't need updating.

When migrating any website to a new host, the first thing you'll want to do is lower the time-to-live (TTL) values of the relevant DNS records to as low as possible.

TTL values tell DNS servers how long to cache your DNS records for.

A higher TTL is good most of the time, because it makes it less likely that your website will become inaccessible if there's an issue with your name servers. It also speeds up requests to your domain, since DNS servers are more likely to have your host address cached.

However, they can significantly delay migrating to a new host because DNS servers across the internet won't be checking for changes as frequently.

  1. Log into your domain registrar, or wherever your DNS records are managed from.

  2. Update your relevant domain record TTLs to the lowest value possible.

Doing this step first means there'll be plenty of time for cached high-TTL domain records to expire.

2. Connecting your Craft CMS codebase #

Servd uses git to pull code and deploy it onto servers. If your Craft CMS code doesn't currently live in a git repository, you'll first need to create one.

  1. Push your codebase to a git repository (preferably one on GitHub, GitLab or Bitbucket).

  2. Sign up for a Servd account or log in if you already have one.

  3. Authenticate with your repository provider when asked, and select the repository you would like to use.

  4. Optionally add your node build command (see below for more detail).

  5. Complete the remainder of the project creation flow.

Once authorized, Servd will pull the code in your repo to create bundles for your project. We have direct integrations with GitHub, GitLab and Bitbucket, and are also able to pull remote repositories that support deploy key authentication.

3. Configuring your front-end build pipeline #

Servd provides an optional, lightweight node build pipeline which allows front-end assets (e.g. JavaScript, CSS, icons) to be built whenever a new bundle is created.

You can specify a single node command and the desired node version during the project creation flow, or alternatively you can set it later in your build & deploy project settings page.

If you don't need to build any front-end assets, or the project's assets are compiled and pushed to the git repo beforehand, then you can just leave the node command empty to skip this step.

Read more about the node build step here.

4. Importing your database data #

Next up, the database import:

  1. First you'll need an SQL dump file of your existing database. These usually have a file extension of .sql, or if they're compressed, .sql.gz or .sql.zip. It's usually a good idea to export them to a compressed format to speed things up later.

  2. Navigate to your staging import page and upload your SQL dump via the "Import Database Dump" upload form. As there's currently nothing in the staging database, you can leave the "Erase all tables before import" checkbox empty. This will upload the file to Servd and begin the import into your staging database.

  3. Wait for the database import to complete. It can take a few minutes to complete depending on how large your existing database is; having a compressed dump file will help speed up the upload part.

  4. You can see the import's current status in the task bar at the bottom of the page. Once you see a ✅ you're done!

It's worth noting that Servd projects run on MariaDB, which is a MySQL-compatible type of database. If your existing database is using PostgreSQL or another non-MYSQL-compatible database, then you'll need to port your dump file before uploading it to Servd.

5. Uploading your local volume assets #

Because of Servd's ephemeral filesystems, local asset volumes aren't guaranteed to persist over any extended period of time - it's one of the ways we make every project highly available. This means any local volumes you have setup on your existing project will start to misbehave when they are on Servd. It's common for assets to start disappearing when the the filesystem of your server is reset (for example, when you sync a new bundle).

So to help set up an alternative to local volumes, we created the Servd Asset Platform and the Servd Assets and Helpers Plugin which provide an easy to use asset storage solution, along with a host of other useful bits of functionality.

If you don't use local asset volumes (e.g. you store all assets remotely in S3) then it's possible to skip this section, however it can still be a good idea to transfer remote volume assets to the Servd CDN to take advantage of the included storage space, as well as the transform and optimisation functionality that the Servd Asset Platform provides.

Here's a few steps on how to get your assets working with Servd:

  1. Install a file transfer tool that supports Backblaze/S3 connections. Popular ones include Cyberduck, Transmit, s3cmd and AWS CLI.

  2. Go to your project's asset settings, and click the "Generate New Access Key" button to create a set of access credentials to the Servd CDN.

  3. Before we start uploading our assets, it's worth taking note of a few things:

    • There are local, staging and production directories already present on the CDN. These correspond to the different environments of your project.
    • It's important to keep the directory structure of your assets the same as your old volume. This will avoid having to re-index all your assets, which can take a long time for remote volumes.
    • If you are uploading assets from multiple volumes, you'll need to supply a "subfolder" for each volume's settings page. Otherwise your files will all get mixed up in the same directory.
    • Your project has an asset storage limit, which all your environments share. Visit your project's plan page to track your current usage. What happens if I exceed the asset storage limit?
  4. Use your file transfer tool of choice to upload your assets into the staging/ directory. This might take a few minutes, so let's carry on to the next step. 👇

  5. Get your project's local development environment up and running on your machine.

    Don't have one yet? We recommend Craft Nitro.

  6. On your local build, install the Servd plugin via composer CLI:

    composer require servd/craft-asset-storage
    

    You should see your composer.json and composer.lock files update.

  7. Run the following to enable the Servd plugin:

    ./craft plugin/install servd-asset-storage

    Or alternatively, navigate to your local Craft plugin settings page and enable the Servd plugin.

    Either way should update your project config files.

  8. Using the details from your project's asset settings, add the following to your .env file:

    SERVD_PROJECT_SLUG=<your project slug>
    SERVD_SECURITY_KEY=<your project security key>
    
  9. In your local control panel, navigate to Settings > Assets. For each local asset volume:

    1. Click the volume from the list.
    2. Select "Servd Asset Storage" from the Volume Type dropdown.
    3. Click Save.

    This will tell Craft to start looking for assets on the Servd CDN, instead of in your local web directory. Your assets will now stop rendering when you view them in the browser, this is because we've not yet uploaded them to the Servd CDN.

  10. Commit all composer and project config file changes and push them to your git repository.

  11. Navigate to your project's staging settings. Create a new bundle using the commit you just made, sync it to staging and wait for the deploy to finish.

  12. Once the assets have finished uploading, visit your project's staging URL and the assets should magically appear. ✨

6. Preparing your production environment #

Once you've reviewed your staging site and are happy that's everything's as it should be, it's time to move onto your production environment in preparation of going live.

  1. Add billing details to your team.

    Alternatively, if your client is going to be responsible for billing, you can invite them to create a Servd team and they can add billing details themselves. Once that's complete, you just need to transfer the project over to their team.

  2. Select a subscription plan to unlock the project's production environment.

  3. Navigate to the production import page.

    In the "Clone From Environment" section, trigger a clone from staging to import the database, assets, selected bundle and new environment variables.

    This will take everything that's in your staging environment and copy it over to production. Depending on how many assets you have and how big your database is, this will likely take a few minutes to complete. Plenty of time to make a coffee. ☕️

  4. Once the clone task completes, you'll probably want to check over your environment variables in the production settings page to make sure anything staging-specific is updated for production. Remember to sync if anything needs changing.

  5. Navigate to your project's domains page. From there, add any domains to your staging and production environments, then click the sync button to deploy the changes.

    Note: this won't trigger requests going to the domain to start going to Servd, that will come later when you switch your DNS records. This change means that any requests to the domain that Servd receives will be routed to your project.

    If you want to add a redirect for the www subdomain, you can select the domain you'd like to redirect from the dropdown.

  6. Next, we need to think about how SSL certificates will work with your domains. Servd provides a couple options:

  7. Now is a good time to explore some of the optional features Servd provides that will make your site a lot quicker and more resilient:

    • Static Caching - enabling static caching can dramatically improve the performance of your site by avoiding unnecessary calls to the database.
    • Cloudflare Integration - Putting Cloudflare in front of your Servd site is a great idea, which is why we made connecting it to your project easy. Their free DDoS protection can get you out of a pickle should an attack happen.
  8. You should now be ready to review your production site and make sure there aren't any issues before going live.

7. Going live #

We're finally ready for the big moment. 🎉

  1. Review your production environment variables again on your production settings page. You'll likely want to update any URLs that were using your project's servd.dev subdomain to your production domain. Sync your project to deploy any changes.

  2. Update your domain DNS records as per the "DNS Instructions" on your project's domains page. This will begin moving traffic from your previous host to Servd.

  3. If you opted to use Servd's automated SSL certificates:

    1. Go to your project's domains page and click the "Check DNS Records" for each of your listed domains. If your DNS records have been setup correctly and the changes have propagated to DNS servers, the domain's "Self Signed" label will switch to "Full".
    2. Sync your project to generate the new certificates. This should take between 1 and 2 minutes and once complete your domain will be fully configured to use a valid SSL certificate and keep your visitors' data safe. 🔒
  4. If everything appears to be working, increase your DNS record TTLs again to improve the availability and resolution speed of your domain.

  5. You're officially now on Servd! 🙌

    If you found this process nice and easy, share the love with the Craft community on Discord and Twitter. Every kind words helps us out a lot.

    If you found it a little tricky, or you found gaps in this guide, please get in touch over our support! We're always on the lookout for ways to make things easier.