.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:

http_settings:
  max_upload_size: "128"

Note: Stack Share websites 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.

Note: “infrastructure” setting has been deprecated. Stacks are now automatically upgraded.

.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

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:

shared_dirs:
  mysite:
    mydir: {}

Virtual stacks can also be configured this way too:

shared_dirs:
  vstack1:
    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

If you remove a shared directory from .platform.yml it will no longer be symlinked into your webroot, 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:

crons:
  mytask_at_eight:
    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 (default is 5.6). Currently supported values are 5.6 and 7.1. You set your PHP version as follows:

php_settings:
  version: 5.6

Please be aware that you must be running at least SilverStripe 3.6.2 to use PHP 7.

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

php_settings:
  cli:
    memory_limit: "1024M"

or alternatively for web server PHP:

php_settings:
  http:
    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:

apache:
  prefork:
    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:

http_settings:
  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. 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.

Note:

  • The first rule that matches will be applied.
  • There is a limit of 49 rules for the base stack and each virtual stack.
url_rules:
  mysite:
    - '<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:

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

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

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.