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:
Preparing your DNS TTLs
Connecting your Craft CMS codebase
Configuring your front-end build pipeline
Importing your database data
Uploading your local volume assets
Preparing your production environment
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.
Log into your domain registrar, or wherever your DNS records are managed from.
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.
Push your codebase to a git repository (preferably one on GitHub, GitLab or Bitbucket).
Authenticate with your repository provider when asked, and select the repository you would like to use.
Optionally add your node build command (see below for more detail).
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.
4. Importing your database data
Next up, the database import:
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.
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.
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.
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 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 Asset Platform to take advantage of the included storage space, as well as the transform and optimisation functionality that it provides.
Here's a few steps on how to get your assets working with Servd:
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.
Connect to the Servd CDN. Here are a few tool-specific guides:
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?
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. 👇
Get your project's local development environment up and running on your machine.
Don't have one yet? We recommend DDEV.
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.
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.
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>
For Craft 3
In your local control panel, navigate to Settings > Assets. For each local asset volume:Click the volume from the list.
Select "Servd Asset Storage" from the Volume Type dropdown.
Click Save.
For Craft 4
In your local control panel, navigate to Settings > Filesystems.For each local asset volume:
Click the filesystem from the list.
Select "Servd Asset Storage" from the Filesystem Type dropdown.
Click Save.
In Craft 4 you also have the option to continue using the local filesystem whilst in local dev. Check out the Servd Plugin Documentation for more info.
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.
Commit all composer and project config file changes and push them to your git repository.
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.
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.
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.
Select a subscription plan to unlock the project's production environment.
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. ☕️
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.
Navigate to your project's domains page. Follow these instructions to add and activate your primary domains for the project.
Note: doing this step 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.
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.
Rate Limiting - rate limiting is enabled by default, but you may want to check whether you're happy with the level it's set to.
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. 🎉
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.
Update your primary domain DNS records as per the "DNS" steps in your project's domains page. This will begin moving traffic from your previous host to Servd.
If everything appears to be working, increase your DNS record TTLs again to improve the availability and resolution speed of your domain.
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.