Skip to content

All about custom config snippets

A custom config snippet is a piece of nginx or Apache configuration you write once and reuse across your sites, instead of pasting the same block into each one.

This article covers creating a snippet, the ready-made ones for Laravel, Craft and WordPress, and the rule that decides which setting wins when two of them set the same thing.

Where to find snippets

Snippets are managed per cluster. Open a cluster, find the 'Custom Config Snippets' section, and click '+' to create one.

Creating a snippet

The 'Create Custom Config Snippet' page has:

  • 'Name' — lowercase letters, digits, dash, underscore. This is what you reference the snippet by.
  • 'Default' toggle — when on, the snippet is automatically appended to every virtual host's custom config on the cluster.
  • 'Server Software' — 'nginx' or 'Apache'. A tile is disabled when the cluster does not support snippets for that software.
  • 'Source' — where the contents come from.

Source: 'Custom Contents'

Reveals a 'Contents' textarea. Paste in any valid config for the chosen server software.

Source: built-in templates

Available only when 'Server Software' is nginx. With Apache, use 'Custom Contents'.

  • 'Laravel' — routing config so Laravel apps receive requests correctly.
  • 'Craft' — routing config for Craft CMS.
  • 'WordPress' — routing config for WordPress.
  • 'Blitz (Craft plugin)' — serves Blitz's cached pages directly, skipping PHP for faster responses.
  • 'Compression' — enables gzip.

Each tile has an eye icon that previews the exact contents that will be saved.

Referencing a snippet in a custom config

Wherever you have a custom config, on a single site or cluster-wide, pull in a snippet's contents with:

{{ custom_config_snippets.name }}

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

Inserting the tag for you

In the cluster-level 'Create Custom Config' page, the 'Snippet' dropdown inserts the {{ … }} block at your cursor in the 'Contents' textarea.

Default snippets and ordering

A snippet marked 'Default' is auto-included in every virtual host's custom config, so you never reference it explicitly.

The ordering rule:

  • Default snippets are appended after the site's own custom config.
  • So when both set the same directive, the default snippet wins, because it comes later.
  • To make a default snippet apply 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

Separate from snippets. Create them in the cluster's 'Custom Configs' section with the '+' button. Only nginx is supported.

They use the same {{ custom_config_snippets.name }} syntax, and are inserted into the nginx global context.

Restriction

When a site has any basic authentication realms attached, do not set the auth_basic or auth_basic_user_file directives in the default context of its custom config. Basic auth manages those itself.