Skip to content

All about custom config snippets

Custom config snippets are reusable pieces of web-server config you can drop into a virtual host's custom config or into a cluster-level custom config. This article covers the create flow, the built-in templates, and the ordering rules you need to know.

Where to find snippets

Snippets are managed per cluster. In Core, open a cluster. The 'Custom Config Snippets' section lists existing snippets, with a '+' button to create one.

Creating a snippet

The 'Create Custom Config Snippet' page has:

  • 'Name': lowercase letters, digits, dash, underscore. The name you'll reference the snippet by.
  • 'Default' toggle: when on, this snippet is automatically appended to every virtual host's custom config on the cluster.
  • 'Server Software': pick 'nginx' or 'Apache'. A tile is disabled if the cluster doesn't support custom config snippets for that software.
  • 'Source': pick where the contents come from.

Source: Custom Contents

Selecting 'Custom Contents' reveals a 'Contents' textarea. Paste in any valid config for the chosen server software.

Source: built-in templates

Several pre-built templates are available, but only when 'Server Software' is nginx. With Apache, you must use Custom Contents.

  • 'Laravel': routing config so Laravel apps receive requests correctly.
  • 'Blitz (Craft plugin)': configures nginx to serve Blitz's cached pages directly, bypassing PHP for faster responses.
  • 'Craft': routing config for Craft CMS.
  • 'WordPress': routing config for WordPress.
  • 'Compression': enables gzip.

Each template tile has a preview, the eye icon, that shows the exact contents that will be saved.

Referencing a snippet in a custom config

Wherever you have a custom config, either on a virtual host or on the cluster, pull in a snippet's contents with:

{{ custom_config_snippets.name }}

Replace name with the snippet's name. The snippet contents are substituted in place when the config is rendered.

In the cluster-level 'Create Custom Config' page, the 'Snippet' dropdown inserts this template tag for you. Picking a snippet drops the right {{ … }} block at your cursor in the 'Contents' textarea.

Default snippets and ordering

When you mark a snippet as 'Default', it's auto-included in every virtual host's custom config, so you never need to reference it explicitly.

There's a subtle ordering rule worth knowing:

  • Default snippets are appended after the virtual host's own custom config.
  • So if both your custom config and a default snippet set the same directive, the default snippet wins, because it appears later.
  • To make a default snippet appear earlier, include it explicitly with {{ custom_config_snippets.name }} at the position you want. The explicit inclusion takes precedence over the automatic append.

Cluster-level custom configs

Separately from snippets, you can create cluster-level 'Custom Configs' in the cluster's 'Custom Configs' section, with the '+' button to create one. Currently only nginx is supported. Cluster-level custom configs use the same {{ custom_config_snippets.name }} syntax to pull in snippets, and they're inserted into the nginx global context.

Restrictions

If a virtual host has any basic authentication realms attached, don't set the auth_basic or auth_basic_user_file directives in the default context of its custom config. Basic auth reserves and manages those itself.