servd

Documentation

Documentation > Assets >

Upgrading to Asset Platform V3

Upgrading to the Servd Asset Platform V3 is a simple process but requires a small amount of preparation.

Important notes #

  • The URLs for your assets will change to use our new CDN and transform functions. If you have hard coded any asset URLs anywhere, they may need to be updated.
  • Asset URLs now have the project name included in the domain instead of the path. You may need to adjust any Custom URL Patterns set in the Servd Plugin's settings to remove this.
  • If you are using a proxy in front of our Asset Platform, such as a Cloudflare Worker, it will need to be updated to point to the new Asset Platform URLs.
  • The Asset Platform V3 supports custom domains for transforms and files. Using a proxy to achieve this is no longer required.
  • If your project returns a Content-Security-Policy header, and you're not currently using a custom asset domain, you'll need to add files.svdcdn.com and transforms.svdcdn.com to the list of trusted domains, otherwise browsers will block assets loaded via those domains.
  • If you're using the image-optimize plugin to manage your asset URLs, then you'll likely need to run ./craft resave/assets after upgrading to see the new v3 asset URLs pull through.
  • We'd recommend against clearing Craft's data cache whilst the migration task is running, as this will trigger the Servd plugin to start rendering v3 asset URLs, which will 404 until the migration task has finished copying asset files over. By default, the Post Deploy Tasks will clear Craft's data cache, so we'd also recommend against deploying new bundles for the same reason.
  • After the upgrade has completed we'll keep all of the existing files intact on the old Asset Platform for 30 days, giving you time to get everything updated and tested before old asset URLs will be deactivated, but any newly uploaded files after the Upgrade will only exist on the new Asset Platform.
  • If you need any help with the migration, just ask! We're happy to help.

  1. Ensure your project has been updated to use the Servd Plugin V3.4.0 (Craft 4) or V2.9.0 (Craft 3).

  2. Build a new bundle containing the updated plugin and roll out to all of your environments. This won't change anything immediately.

  3. In the Servd dashboard, visit your project's Assets page.

  4. Under the "Upgrade to Asset Platform V3" section, click the "Upgrade Now" button.

    The migration process might take a few minutes to complete if you have lots of files - you can see the file copy progress in the Task Bar at the bottom of most pages in the dashboard.

  5. Once done, run a Sync to update your Staging and Production environments with the new configuration and switch them to the new asset platform.

    In local development, the Servd plugin will now automatically detect that the upgrade has taken place and update your file and image URLs appropriately - you'll just need to clear Craft's data cache if this is picked up straight away.

  6. (Optional) You may wish to configure custom URLs for your assets at this point. If so, you can check how to do that here.

  7. If your project is using any form of caching (static, blitz or {% cache %} tags) clear them to refresh all of your project's HTML with the updated asset URLs. You might want to wait for a quiet traffic period to perform this step if your project relies on caching to handle its normal load.

  8. You're fully upgraded!