.platform.yml file

SilverStripe Platform stack configuration can be customised to a degree, through use of a .platform.yml that resides in the root of your site code.

An example .platform.yml file:

  max_upload_size: "128"

Note: Sites running on virtual stacks do not require the .platform.yml file. It will be ignored, as the infrastructure configuration is set at the base stack.

.platform.yml options

This YML-formatted file currently supports the following options:

Option Description Example Required?
shared_dirs Specify shared directories to create and link into the webroot of the deployed site. see Shared directories no
crons Specify cron tasks to be executed on a schedule. see Cron tasks no
php_settings Specify PHP settings (including PHP version). see PHP settings no
apache Specify Apache settings. see Apache settings no
http_settings Specify web server settings. see HTTP settings no
url_rules Specify location blocks in Nginx see URL rules no
packages Specify optional packages to load on your stack see Packages no

Shared directories

You can specify directories that will be persisted across multiple deployments. One built-in example of this is the assets directory, but this allows you to specify your own.

In this example we will create mydir. We use the mysite key to identify that this will be a shared directory on the base environment, to distinguish between base and virtual stacks:

    mydir: {}

Virtual stacks can also be configured this way too:

    mydir: {}

In this case the virtual stack is called vstack1. You can find the name of your virtual stack by clicking the “stack selector” field while viewing an environment in the Platform Dashboard:

Platform Dashboard stack selector

Your shared directory is accessible from the web root and public by default. For the example above, a file called example.txt within your shared directory can be accessed by visiting https://site.com/mydir/example.txt

If you use a shared directory with the same name as an existing file or folder within your web root, the shared directory will take precedence and overwrite the existing file or folder.

If you remove a shared directory from .platform.yml it will no longer be symlinked into your web root, but for safety reasons it will not be removed from the storage volume. Please contact the Helpdesk if you require data to be purged.

Cron tasks

The recommended method for running recurring tasks on SilverStripe Platform is with a CronTask; however if this doesn’t suit your needs, you can specify cronjobs directly. Please note that this is considered advanced usage, so ensure that you understand the differences and factor in the possibility of the task running on multiple servers at once. There are three types of cron you can choose to run:

Key Description
sake_once A command that will run via SilverStripe Framework’s sake, and only be executed once, regardless of the number of servers in your stack. Best for isolated tasks and most common option.
sake_all A command that will run via SilverStripe Framework’s sake on every server in the stack in parallel. Best for updating something on the filesystem that is otherwise not synced or shared.
command (Advanced) A raw command - this can be anything you want to execute, and by default will run on every server at once. To limit to one server, preface your command with /usr/local/bin/sera 0 - this will add a database lock to the command to ensure that it can only be run once per stack.

For example, to run a task at 20:00 (8pm) daily:

    time: "0 20 * * *"
    sake_once: "dev/tasks/MyTask"
    vhost: "mysite"

Where the vhost parameter matches your virtual stack name - or mysite for a base stack. This will automatically log to Graylog with the logtype SilverStripe_cron_mytask_at_eight for easy filtering.

Note that these crons will always run under the webserver user.

PHP settings

Here you can define your PHP version. Currently supported values are 7.1, 7.2, and 7.3. You set your PHP version as follows:

  version: 7.3

PHP versions are supported for two years after their initial release, with an additional year for critical security issues only. We recommend keeping your PHP version up to date and set to the latest version.

  • PHP 5.6: no longer supported and at risk of security vulnerabilities
  • PHP 7.1: security support ends 1st December 2019
  • PHP 7.2: active support ends 30th November 2019, security support ends 30th November 2020
  • PHP 7.3: active support ends 6th December 2020, security support ends 6th December 2021

You can change settings that apply for command line PHP like so:

    memory_limit: "1024M"

or alternatively for web server PHP:

    max_execution_time: "60"

See PHP ini settings docs for more information on which individual settings can be used.

Apache settings

Apache prefork settings can be tuned by setting the following:

    startservers: "3"
    minspareservers: "2"
    maxspareservers: "5"
    maxclients: "30"
    serverlimit: "30"
    maxrequestsperchild: "10000"

See Apache MPM prefork docs for more information on individual settings above.

HTTP settings

This is used to alter a server-wide setting, for example:

  max_upload_size: "128" # This value will be converted into MB
  timezone: "Europe/London"

The max_upload_size setting will adjust PHP and nginx limits accordingly to increase the maximum upload size for your stack. This will also increase the post_max_size in PHP, so there is no need to change that setting as well.

Note that this setting will not work if the PHP ini settings for upload_max_filesize and post_max_size have been changed in .htaccess or calls to ini_set in your site code. We don’t recommend using either of these methods for setting config from code.

The timezone setting will adjust the PHP date.timezone setting, the system timezone of the host machine, and the SS_DATABASE_TIMEZONE configuration in the environment file.

Please see the PHP documentation for a list of valid timezones. Please also be aware that these settings will apply across all virtual stacks on the environment.

URL rules

SilverStripe Platform uses a combination of webservers for improved performance. As a rule of thumb, media files and assets will be served directly by Nginx by default, such as:

  • CSS
  • JavaScript
  • Images (JPG, PNG, GIF, BMP, ICO, SVG)
  • Plain-text files (TXT, HTM, HTML)
  • Fonts (WOFF, WOFF2, OTF, TTF, EOT)

Everything else will be passed to Apache for a much slower PHP invocation.

URL rules make this behaviour customisable. We use “mysite” to denote base stack, but the rules can be defined for virtual stacks too.


  • The first rule that matches will be applied.
  • There is a limit of 49 rules for the base stack and each virtual stack.
    - '<regex>': '<rule>'
    - '<regex>': '<rule>'
    - ...
  <virtual stack name>:
    - '<regex>': '<rule>'
    - '<regex>': '<rule>'
    - ...

The regex must be in a format accepted by Nginx. This will be used as a case-insensitive location matcher and is compared against the full URL - some examples are provided in the table below. For a better explanation of what this means, please see Nginx location docs.

  • \.(gif|jpg|jpeg)$ - match extensions at the end of the URL
  • ^/assets/ - match all URLs pointing to the assets directory

Each URL must be accompanied by one of the following rules:

  • apache - requests are passed through to Apache. If they were previously served by Nginx, they will now be several orders of magnitude slower, but .htaccess will be respected. This is a requirement for the secure assets module.
  • nginx - Nginx will attempt to serve these URLs directly from disk. This is a rule normally associated with assets and media files.
  • deny - deny all access through Nginx.
  • nginx-with-passthrough - available in infrastructure version 3.13.0 and up only. Nginx will attempt to serve these URLs directly from disk, if the file is not found it will be served by Apache. Note that this means all 404s from the specified directory will be served by Apache which can be bad for performance.

Example: set up base stack to use secure assets, and myvstack to deny access to a hidden file:

    - '^/assets/': 'apache'
    - '^/assets/secretassets/topsecretfile.pdf$': 'deny'

See Redirecting to HTTPS for details on how to redirect all requests based on their protocol.


SilverStripe Platform offers additional packages that you can install on your environments to aid debugging or performance monitoring. These packages are provided as-is and support for these third-party packages is limited.

These packages require a full deployment to your environments to add or remove them. For Multi-AZ stacks these are installed on every server for your environment.


Blackfire is a profiling tool and can be used to identify bottlenecks or areas of high resource consumption for your PHP application.

As with any profiling tool this package can have a slight impact on the performance of your website. We recommend you only enable Blackfire for your non-Production environments.

To install Blackfire for your UAT environment only, add the following configuration to your .platform.yml file:

        server_id: "<server ID>"
        server_token: "<server token>"

Your server ID and token are validated during a full deployment, and incorrect credentials may cause the deployment to fail.

New Relic

The New Relic agent monitors your application to identify performance issues or bottlenecks.

To install the New Relic agent, add the following configuration to your .platform.yml file:

    appname: "<name for your stack>"
    license_key: "<license key from New Relic>"

appname is a customizable field that can be used to identify your particular website within New Relic.

MySQL settings

The database version can’t be configured yet. Please (contact support) to find out which version you’re running. All databases on SilverStripe Platform are compatible with at least MySQL 5.6.