servd

Servd Asset Volumes and Filesystems

Once the plugin is installed and configured you will be able to create "Servd Asset Storage" Volumes (Craft 3) and Filesystems (Craft 4) within the settings of Craft's Control Panel.

The default configuration for these volumes will work without any tweaks. You can test it out by uploading an image to your new volume and ensuring a thumbnail is generated and displayed.

Multiple Servd Volumes #

You can create multiple Servd Asset Volumes within a single project to help keep things organised. However, if you do this you will need to supply a subfolder for each volume otherwise your files will all get mixed up and Craft's asset re-indexing will fail.

Environment Detection #

The plugin will automatically separate your assets within the Servd Assets Platform depending on the environment that they were uploaded from. By default it will split your assets into the following:

• local
• staging
• production

This ensures that changes you make to assets in one environment do not impact the assets in another.

If you connect to the Servd Asset Platform using an S3 client, you'll see these three directories in the root of your storage.

Using these standard environment names also allows Servd to include assets in any clone operations performed via the Servd dashboard, i.e. if you perform a full clone from staging -> production the platform is able to copy your assets from the staging directory, into the production directory.

Forcing a Specific Environment #

If you wish to prevent the plugin from auto-detecting the current environment (so that you can, say, interact with production assets whilst working locally for example) you can override the environment detection using the Assets Volume Environment setting in the main plugin settings. We advise that you set this to an environment variable so that you can tweak it dynamically as required.

Note: we generally don't recommend this approach if assets will likely be edited independently in each environment. This is because Craft tracks the assets it has available to it in it's database, which is separate from the files stored on the Servd CDN.

E.g. say you configured your staging and production environments to both refer to the production asset volume environment, and then deleted an asset via your staging control panel. This would delete the asset from the staging database and also the file from the production asset volume on the Servd CDN. Unfortunately, the production environment would still think the asset exists and attempt to render it, but as the file from the CDN has been deleted, it would fail and present a broken image.

How the Image Optimisation works #

The Servd Plugin's image optimisation performs the following steps:

1. In your codebase, you generate a URL for an asset e.g. myAsset.getUrl(...).
2. The plugin intercepts this request and returns a URL pointing to the Servd CDN with all of your transform options included. This URL is rendered in your HTML output.
   
3. The end user's browser then makes a request for this image URL. The Servd CDN checks for a cached copy of the transformed URL and returns it if it exists. If not, the request is passed along to a cloud function to perform the transformation.
4. The cloud function pulls in your original image, then uses SharpJS to apply the transforms which were encoded in the URL.
5. The resulting image is stored in a secondary cache before being sent back to the CDN to be delivered to the end user.

All of the above should happen automatically without requiring any input from your side - as long as the Servd Plugin is inserting the correct URLs into your HTML everything should happen automatically.

Disabling Servd Asset Platform Transforms and Optimisations #

If you'd like to use Craft's default asset transform functionality, or you'd just like the Servd plugin to return links to all original uploaded assets instead of pre-optimised ones, you can disable all off server transforms and optimisations using the 'Disable Asset Platform image transforms / optimisations' switch in the plugin settings.

If this is switched on Servd Asset Volumes will begin acting just like standard S3 Asset Volumes - relying on GD, ImageMagick or another plugin to perform any required transformations.

This can also be useful if you're setting up a statically generated site and would like to process your images using a 3rd party platform.

Using a Custom Domain For Assets #

The Custom CDN URL Pattern and Custom Image Transform URL Pattern asset filesystem settings can be used to specify a custom domain name and URL pattern to use for transformed and untransformed files. You can read more about how to set that up here.

The URL pattern fields make use of string placeholders that the Servd plugin will dynamically replace when the asset URLs are rendered. The available placeholders are as follows:

• {{environment}} - by default this will be either "local", "development", "staging" or "production" depending on the environment the Servd plugin is running in. You can also force it to be a specific environment too.
• {{subfolder}} - this corresponds to the "Subfolder" field in your Servd asset filesystem. If one isn't set, we'd recommend omitting this placeholder.
• {{filePath}} - this translates to the combined subpath and filename of the asset.
• {{params}} - this is specific to the "Custom Image Transform URL Pattern" field. It contains all the necessary query parameters to transform assets to specific dimensions.

A typical "Custom CDN URL Pattern" value would look something like:

And a typical "Custom Image Transform URL Pattern" value would look something like:

Base URL #

Because of the dynamic nature of the URLs outputted by assets stored on the Servd Asset Platform, the "Base URL" field on your volume/filesystem is largely overidden, but it should generally be set to:

where project-slug is your specific Servd project's slug.