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 helps you insert this template tag without typing — picking a snippet inserts 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 — 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 (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, '+' button to create). 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.