Documentation

The Servd Plugin

On Servd, local asset volumes aren't guaranteed to persist over any extended period of time - it's one of the ways we make high availability work on every project.

To help you 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.

Installing The Plugin With Composer

The preferred method of installing the plugin is via composer on the command line. The following will add he latest version of the plugin to your project:

composer require servd/craft-asset-storage

Once downloaded you'll also need to enable the plugin on Craft's Plugin settings page.

Installing The Plugin Via The Control Panel

  1. Navigate to the Plugin Store in the Craft control panel

  2. Search for 'Servd'

  3. Select the 'Servd Assets and Helpers' plugin, scroll down and click 'Install'

Getting Started

If you would like to use Servd Asset Storage volumes during local development you will need to fill in the Servd Project Slug and Servd Security Key settings. The values for these can be found in the Servd dashboard under Project Settings > Assets.

The plugin will automatically try to load these values from the environment variables SERVD_PROJECT_SLUG and SERVD_SECURITY_KEY, so you can simply add these two environment variables to your local dev environment to get things working.

Alternatively, you can add them directly to the plugin's settings in the Craft Control Panel in which case they will be added to your Craft Project Config files (so make sure they are kept secret!).

Servd Asset Volumes

Once the plugin is installed and configured you will be able to create 'Servd Asset Storage' volumes within the asset 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 E.G. interact with production assets whilst working locally) 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.

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 Optimise URL Pattern volume settings can be used to specify a custom domain name and URL pattern to use for optimised and unoptimised files. You can read more about how to set that up here.

Static Caching

Servd has a static caching solution which is available for all projects to make use of. This plugin provides deep integration with your project's static cache by allowing brute force or intelligent cache purges to occur. You can select when the cache is purged and what strategy is used to perform the purge within the plugin settings.

Trigger - None

The cache will never be automatically purged in any way.

Trigger - Only when entries are updated via the control panel

The cache will only be purged if a Craft Entry is updated from within the control panel. This prevents purges from occurring when an end-user submits a form from the front end or makes a Commerce purchase - both of which might edit an Entry, but not from the control panel.

Trigger - When entries are updated in any way

The cache will be purged whenever an Entry is saved, no matter where the request originated from.

Strategy - Full Purge

A full purge will destroy the entire static cache immediately whenever a 'live' Craft Element is updated (not disabled or a draft). This is a brute force approach, but it ensures that any changes you have made are displayed on the front end immediately with no chance of any cached pages pages surviving.

Strategy - Automated Tag Based Purge

This purge mechanism tracks all of the Craft Elements which are loaded in order to render each URL on your site. These Element -> URL associations are stored within an efficient data structure for later retrieval.

When any 'live' Craft Element is updated, the plugin is able to determine which URLs need to be purged based on the Element -> URL associations and only these URLs are purged. This prevents sudden surges of traffic from reaching PHP due to a full cache purge, but relies on a relatively complex tagging system on the back end which might, in some edge case circumstances, result in some URLs being missed from purges.

Manual Cache Purges

As well as the built-in automatic cache purging mechanisms, the plugin also provides several ways to manually purge cached URLs:

  • On the Utilities > Clear Caches page in the Craft Control Panel, you have the option to fully purge the static cache by checking the Servd Static Cache check box.
  • On the edit page for any Craft Entry which has an associated URL, you will find buttons which allow you to purge the Entry's cache specifically, or purge any URLs which are associated with the Entry.
  • Use the Craft CLI command ./craft clear-caches/servd-static-cache

CSRF Token Injection

By default Craft uses CSRF tokens within <form> elements. Static caching breaks this functionality by serving incorrect tokens to the majority of users. In order to prevent this you can enable CSRF token injection in the Servd Plugin settings. This will inject a small piece of javascript into all of your templated pages which checks for any CSRF tokens and replaces them with an uncached value.

Dynamic Content

Sometimes it's useful to be able to have specific sections of a page dynamic whilst keeping the majority of the page cached. The plugin contains a twig tag which can do this on your behalf:

{{ dynamicInclude 'snippets/login' with {key: 'val'} only }}

The tag matches the syntax of the standard twig {{ include }} tag exactly, so you can easily switch between standard and dynamic template includes.

This mechanism relies on Craft's action URL prefix being excluded from the static cache. Servd has this in place by default, but you might need to update it if you use a non-standard action URL prefix.

Dynamic Content Context

As with the normal {{ include }} tag, the vast majority of the parent template's context will be made available to the dynamically loaded template by default. You can prevent the full context from being used by specifying the only flag.

Due to the way the dynamic loading works, any simple data types (strings, numbers, arrays etc) in the parent context will be exposed publicly. This does not include any of Craft's global twig variables however. If you have sensitive content in your template context, always use the only flag and define your child template's context explicitly.

Dynamic Content Placeholder

If you would like to include some placeholder content which will display while your dynamic content is being loaded, you can add the placeholder flag. This flag must be the last one on the tag.

Once this has been added, a closing tag is also required and any content between the two will be used as the placeholder content:

{{ dynamicInclude 'snippets/login' with {key: 'val'} only placeholder }}
{{-- Placeholder content can go in here --}}
<a href="/">Login!</a>
{{ endDynamicInclude }}

The placeholder content will be contained within a single, unstyled <div> and will be removed automatically when the dynamic content is ready.

You can use this to easily include a loading graphic, a null state, or some default content for when the end-user has javascript disabled.

Dynamic Content ESI

If you have ESI enabled on Servd, the plugin will automatically detect this and switch {{ dynamicInclude }}s to use ESI instead of ajax requests, resulting in extremely quick page load times. No changes are required to your codebase. The implementation of ESI inclusion using this tag is... interesting, and relies on javascript being enabled on the client. If you're interested in why that's the case, we're always happy to talk tech.

Local Development Tooling

The plugin contains several features which aim to make local development a smoother process and save you time.

Force Local Volumes for Assets

You can force the use of local volumes when working outside of Servd to make development work a little quicker. To do so, just flip the Use Local Volumes During Dev switch in the plugin settings. This will convert all Servd Asset Volumes into Local Volumes during local dev, but keep them unchanged when running inside Servd itself. This setting also ensures that the Local Volume override does not leak into any Project Config files or database data which might inadvertently break the staging or production environment.

This setting is very useful if you have multiple developers working on a single project and they all need to keep track of their own sets of assets. It also ensures that assets used during local development do not count towards your Servd Asset Platform usage total.

This setting ignores the Assets Volume Environment setting (see Forcing a Specific Environment above) and will be applied regardless of any value added there.

Sync Assets

You can sync your assets from local to staging/production, or from staging/production to local. If you are using remote storage during local development (the default) this will simply trigger a clone task to copy the asset files between directories in the Servd Asset Platform. If you have Use Local Volumes During Dev enabled this will sync assets between your local filesystem and the specified remote storage directory.

You can trigger asset syncs using the following commands:

./craft servd-asset-storage/local/pull-assets

./craft servd-asset-storage/local/push-assets

These commands will try their best to auto-detect all of the settings they need, even before Craft has been installed. If it cannot identify specific settings it will prompt you for them, or you can supply them via CLI flags:

./craft servd-asset-storage/local/pull-assets --from=staging --servdSlug=my-project-slug --servdKey=my-servd-key --interactive=0

./craft servd-asset-storage/local/push-assets --to=production --servdSlug=my-project-slug --servdKey=my-servd-key --interactive=0

Pull/Push Local Database

You can pull down a database from Servd or push up your local database at any time using the commands:

./craft servd-asset-storage/local/pull-database

./craft servd-asset-storage/local/push-database

These commands will try their best to auto-detect all of the settings they need, even before Craft has been installed. If it cannot identify specific settings it will prompt you for them, or you can supply them via CLI flags:

./craft servd-asset-storage/local/pull-database --from=staging --servdSlug=my-project-slug --servdKey=my-servd-key --skipBackup=1 --interactive=0

./craft servd-asset-storage/local/push-database --to=production --servdSlug=my-project-slug --servdKey=my-servd-key --interactive=0

Please note that while a database is being pushed to a Servd, the target environment is likely to become unresponsive

Integration with Imager-X

The plugin contains storage and transform adapters for ImagerX. These allow you to use the ImagerX template syntax whilst utilising Servd's Asset Platform for storage, optimisation and transformation of your images.

You can use any combination of the storage and transformer components as you wish. Here are a few example ImagerX configurations:

Use Servd For Everything (only works with Images stored on a Servd Assets Volume)

return [
    'transformer' => 'servd',
];

Use Servd For Storage Of Transformed Images Only (assets transformed on-server - should work with source assets stored anywhere)

return [
    'storages' => ['servd'],
    'storageConfig' => [
        'servd' => [
            'folder' => 'transforms',
        ]
    ],
    'imagerUrl' => 'https://cdn2.assets-servd.host/[you-servd-project-slug]/transforms/',
];

Use Imgix For Transforms, Servd For Storage (only works with Images stored on a Servd Assets Volume)

return [
    'transformer' => 'imgix',
    'imgixConfig' => [
        'default' => [
            'domain' => '[your-imgix-domain].imgix.net',
            'useHttps' => true,
            'useCloudSourcePath' => true,
        ]
    ]
];

Combine the above with an imgix 'Web Folder' source set up to point to https://cdn2.assets-servd.host/

Integration with ImageOptimise

The plugin contains a transform adaptor for ImageOptimize. Simply select 'Servd' as the active transformer in ImageOptimise's settings and ensure it isn't being overridden by an imageoptimise.php config file.

If you'd like to pre-generate resized images (not really necessary and can slow down the Craft CP) add the ImageOptimise Optimized Images Field to the Servd Asset Volume's fieldset.