silverstripe-framework/docs/en/00_Getting_Started/00_Server_Requirements.md

---
title: Server Requirements
icon: server
summary: What you will need to run Silverstripe CMS on a web server
---

# Requirements

Silverstripe CMS needs to be installed on a web server. Content authors and website administrators use their web browser
to access a web-based GUI to do their day-to-day work. Website designers and developers require access to the files on
the server to update templates, website logic, and perform upgrades or maintenance.

## PHP

* PHP >=7.4
* PHP extensions: `ctype`, `dom`, `fileinfo`, `hash`, `intl`, `mbstring`, `session`, `simplexml`, `tokenizer`, `xml`
* PHP configuration: `memory_limit` with at least `48M`
* PHP extension for image manipulation: Either `gd` or `imagick`
* PHP extension for a database connector (e.g. `pdo` or `mysqli`)

Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your configuration.

Silverstripe CMS tracks the official [PHP release support timeline](https://www.php.net/supported-versions.php). When a PHP version reaches end-of-life, Silverstripe CMS drops support for it in the next minor release. 

## Database

* MySQL >=5.6 (
  built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
* PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community
  supported)
* SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
* SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)

### Default MySQL Collation

In Silverstripe CMS Recipe 4.7 and later, new projects default to the `utf8mb4_unicode_ci` collation when running
against MySQL, which offers better support for multi-byte characters such as emoji. However, this may cause issues
related to Varchar fields exceeding the maximum indexable size:

- MySQL 5.5 and lower cannot support indexes larger than 768 bytes (192 characters)
- MySQL 5.6 supports larger indexes (3072 bytes) if the `innodb_large_prefix` setting is enabled (but not by default)
- MySQL 5.7 and newer have `innodb_large_prefix` enabled by default
- MariaDB ~10.1 matches MySQL 5.6's behaviour, >10.2 matches 5.7's.

You can rectify this issue by upgrading MySQL, enabling the `innodb_large_prefix` setting if available, or reducing the
size of affected fields. If none of these solutions are currently suitable, you can remove the new collation
configuration from `app/_config/mysite.yml` to default back to the previous default collation.

Existing projects that upgrade to Recipe 4.7.0 will unintentionally adopt this configuration change. Recipe 4.7.1 and
later are unaffected. See [the release notes](/changelogs/4.7.0/#default-mysql-collation-updated) for more information.

### Connection mode (sql_mode) when using MySQL server >=5.7.5

In MySQL versions >=5.7.5, the `ANSI` sql_mode setting behaves differently and includes the `ONLY_FULL_GROUP_BY`
setting. It is generally recommended to leave this setting as-is because it results in deterministic SQL. However, for
some advanced cases, the sql_mode can be configured on the database connection via the configuration API (
see `MySQLDatabase::$sql_mode` for more details.) This setting is only available in Silverstripe CMS 4.7 and later.

 ### MySQL/MariaDB Int width in schema

MySQL 8.0.17 stopped reporting the width attribute for integers while MariaDB did not change its behaviour.
This results in constant rebuilding of the schema when MySQLSchemaManager expects a field to look like e.g.
`INT(8)` and MySQL server reports it simply as `INT`. MySQLSchemaManager has been updated to detect the MySQL
server implementation and act accordingly. In cases when auto-detection fails, you can force the desired behaviour like this:
```yml
SilverStripe\ORM\Connect\MySQLSchemaManager:
    schema_use_int_width: true # or false when INT widths should be ignored
```

## Webserver Configuration

### Overview

Silverstripe CMS needs to handle a variety of HTTP requests, and relies on the hosting environment to be configured securely
to enforce restrictions. There are secure defaults in place for Apache, but you should be aware of the configuration
regardless of your webserver setup.

### Public webroot

The webroot of your webserver should be configured to the `public/` subfolder. Projects created prior to Silverstripe CMS
4.1 might be using the main project folder as the webroot. In this case, you are responsible for ensuring access to
system files such as configuration in `*.yml` is protected from public access. We strongly recommend switching to more
secure hosting via the `public/`. See [4.1.0 upgrading guide](/changelogs/4.1.0).

### Filesystem permissions

During runtime, Silverstripe CMS needs read access for the webserver user to your base path (including your webroot). It
also needs write access for the webserver user to the following locations:

* `public/assets/`: Used by the CMS and other logic to [store uploads](/developer_guides/files/file_storage)
* `TEMP_PATH`: Temporary file storage used for the default filesystem-based cache adapters in
  [Manifests](/developer_guides/execution_pipeline/manifests), [Object Caching](/developer_guides/performance/caching)
  and [Partial Template Caching](/developer_guides/templates/partial_template_caching).
  See [Environment Management](/getting_started/environment_management).
* `.graphql-generated`: silverstripe/graphql version 4 introduces this directory. This is where your schema is
  stored once it [has been built](/developer_guides/graphql/getting_started/building_the_schema). Best practice
  is to create it ahead of time, but if the directory doesn't exist and your project root is writable, the graphql
  module will create it for you.
* `public/_graphql`: silverstripe/graphql version 4 introduces this directory. It's used for
  [schema introspection](/developer_guides/graphql/tips_and_tricks#schema-introspection). You should treat this folder
  the same way you treat the `.graphql-generated` folder.

[info]
If you are still using silverstripe/graphql 3.x, you do not need the `.graphql-generated` or `public/_graphql` directories.
[/info]

If you aren't explicitly [packaging](#building-packaging-deployment)
your Silverstripe CMS project during your deployment process, additional write access may be required to generate supporting
files on the fly. This is not recommended, because it can lead to extended execution times as well as cause
inconsistencies between multiple server environments when manifest and cache storage isn't shared between servers.

Note that permissions may be required for other directories for specific functionality - for example if you use the
[i18nTextCollector](api:SilverStripe\i18n\TextCollection\i18nTextCollector) you will need to provide write access to the
relevant i18n `lang` directories.

### Assets

Silverstripe CMS allows CMS authors to upload files into the `public/assets/` folder, which should be served by your
webserver. **No PHP execution should be allowed in this folder**. This is configured for Apache by default
via `public/assets/.htaccess`. The file is generated dynamically during the `dev/build` stage.

Additionally, access is whitelisted by file extension through a dynamically generated whitelist based on
the `File.allowed_extensions` setting
(see [File Security](/developer_guides/files/file_security#file-types)). This whitelist uses the same defaults
configured through file upload through Silverstripe CMS, so is considered a second line of defence.

### Secure Assets {#secure-assets}

Files can be kept in draft stage, and access restricted to certain user groups. These files are stored in a
special `.protected/` folder (defaulting to `public/assets/.protected/`).
**Requests to files in this folder should be denied by your webserver**.

Requests to files in the `.protected/` folder are routed to PHP by default when using Apache,
through `public/assets/.htaccess`. If you are using another webserver, please follow our guides to ensure a secure
setup. See [Developer Guides: File Security](/developer_guides/files/file_security) for details.

For additional security, we recommend moving the `.protected/` folder out of `public/assets/`. This removes the
possibility of a misconfigured webserver accidentally exposing these files under URL paths, and forces read access via
PHP.

This can be configured via [.env](/getting_started/environment_management) variable, relative to the `index.php`
location.

```
SS_PROTECTED_ASSETS_PATH="../.protected/"
```

The resulting folder structure will look as follows:

```
.protected/
  <hash>/my-protected-file.txt
public/
  index.php
  assets/
    my-public-file.txt
vendor/
app/
```

Don't forget to include this additional folder in any syncing and backup processes!

### Building, Packaging and Deployment {#building-packaging-deployment}

It is common to build a Silverstripe CMS application into a package on one environment (e.g. a CI server), and then deploy
the package to a (separate) webserver environment(s). This approach relies on all auto-generated files required by
Silverstripe CMS to be included in the package, or generated on the fly on each webserver environment.

The easiest way to ensure this is to commit auto generated files to source control. If those changes are considered too
noisy, here's some pointers for auto-generated files to trigger and include in a deployment package:

* `public/_resources/`: Frontend assets copied from the (inaccessible) `vendor/` folder
  via [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
  See [Templates: Requirements](/developer_guides/templates/requirements#exposing-assets-webroot).
* `.graphql-generated/` and `public/_graphql/`: Schema and type definitions required by CMS and any GraphQL API endpoint.
  Generated by
  [silverstripe/graphql v4](https://github.com/silverstripe/silverstripe-graphql). See
  [building the schema](/developer_guides/graphql/getting_started/building_the_schema) and
  [deploying the schema](/developer_guides/graphql/getting_started/deploying_the_schema).
* Various recipes create default files in `app/` and `public/` on `composer install`
  and `composer update` via
  [silverstripe/recipe-plugin](https://github.com/silverstripe/recipe-plugin).

### Web Worker Concurrency

It's generally a good idea to run multiple workers to serve multiple HTTP requests to Silverstripe CMS concurrently. The
exact number depends on your website needs. The CMS attempts to request multiple views concurrently. It also
routes [protected and draft files](/developer_guides/files/file_security)
through Silverstripe CMS. This can increase your concurrency requirements, e.g. when authors batch upload and view dozens of
draft files in the CMS.

When allowing upload of large files through the CMS (through PHP settings), these files might be used
as [protected and draft files](/developer_guides/files/file_security). Files in this state get served by Silverstripe CMS
rather than your webserver. Since the framework uses [PHP streams](https://www.php.net/manual/en/ref.stream.php), this
allows serving of files larger than your PHP memory limit. Please be aware that streaming operations don't count towards
PHP's [max_execution_time](https://www.php.net/manual/en/function.set-time-limit.php), which can risk exhaustion of web
worker pools for long-running downloads.

### URL Rewriting

Silverstripe CMS expects URL paths to be rewritten to `public/index.php`. For Apache, this is preconfigured
through `.htaccess` files, and expects using the `mod_rewrite` module. By default, these files are located
in `public/.htaccess` and `public/assets/.htaccess`.

### HTTP Headers

Silverstripe CMS can add HTTP headers to responses it handles directly. These headers are often sensitive, for example
preventing HTTP caching for responses displaying data based on user sessions, or when serving protected assets. You need
to ensure those headers are kept in place in your webserver. For example, Apache allows this
through `Header setifempty` (see [docs](https://httpd.apache.org/docs/current/mod/mod_headers.html#header)).
See [Developer Guide: Performance](/developer_guides/performance/)
and [Developer Guides: File Security](/developer_guides/files/file_security) for more details.

Silverstripe CMS relies on the `Host` header to construct URLs such as "reset password" links, so you'll need to ensure that
the systems hosting it only allow valid values for this header.
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.

### CDNs and other Reverse Proxies

If your Silverstripe CMS site is hosted behind multiple HTTP layers, you're in charge of controlling which forwarded headers
are considered valid, and which IPs can set them.
See [Developer Guide: Security - Request hostname forgery](/developer_guides/security/secure_coding#request-hostname-forgery)
.

### Symlinks

Silverstripe CMS is a modular system, with modules installed and updated via the `composer` PHP dependency manager. These
are usually stored in `vendor/`, outside of the `public/` webroot. Since many modules rely on serving frontend assets
such as CSS files or images, these are mapped over to the `public/_resources/` folder automatically. If the filesystem
supports it, this is achieved through symlinks. Depending on your hosting and deployment mechanisms, you may need to
configure the plugin to copy files instead.
See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin) for details.

### Caches

Silverstripe CMS relies on various [caches](/developer_guides/performance/caching/)
to achieve performant responses. By default, those caches are stored in a temporary filesystem folder, and are not
shared between multiple server instances. Alternative cache backends such as Redis can be
[configured](/developer_guides/performance/caching/).

While cache objects can expire, when using filesystem caching the files are not actively pruned. For long-lived server
instances, this can become a capacity issue over time - see
[workaround](https://github.com/silverstripe/silverstripe-framework/issues/6678).

### Error pages

The default installation
includes [silverstripe/errorpage](https://addons.silverstripe.org/add-ons/silverstripe/errorpage), which generates
static error pages that bypass PHP execution when those pages are published in the CMS. Once published, the static files
are located in `public/assets/error-404.html` and `public/assets/error-500.html`. The default `public/.htaccess` file is
configured to have Apache serve those pages based on their HTTP status code.

### Other webservers (Nginx, IIS, Lighttpd)

Serving through webservers other than Apache requires more manual configuration, since the defaults configured
through `.htaccess` don't apply. Please apply the considerations above to your webserver to ensure a secure hosting
environment. In particular, configure protected assets correctly to avoid exposing draft or protected files uploaded
through the CMS.

There are various community supported installation instructions for different environments. Nginx is a popular choice,
see [Nginx webserver configuration](https://forum.silverstripe.org/t/nginx-webserver-configuration/2246).

Silverstripe CMS is known to work with Microsoft IIS, and generates `web.config` files by default
(
see [Microsoft IIS and SQL Server configuration](https://forum.silverstripe.org/t/microsoft-iis-webserver-and-sql-server-support/2245))
.

Additionally, there are community supported guides for installing Silverstripe CMS on various environments:

* [Hosting via Bitnami](https://bitnami.com/stack/silverstripe/virtual-machine): In the cloud or as a locally hosted
  virtual machine
* [Vagrant/Virtualbox with CentOS](https://forum.silverstripe.org/t/installing-via-vagrant-virtualbox-with-centos/2248)
* [macOS with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
* [macOS with MAMP](https://forum.silverstripe.org/t/installing-on-osx-with-mamp/2249)
* [Windows with WAMP](https://forum.silverstripe.org/t/installing-on-windows-via-wamp/2250)
* [Vagrant with silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
* [Vagrant with BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)

### Email

Silverstripe CMS uses SwiftMailer to send email messages. New installations setup with silverstripe/installer are configured to use a `sendmail` found in `/usr/sbin/sendmail` or another location specified via configuration. Alternatively email can be configured to use SMTP or other mail transports instead of sendmail.

You _must_ ensure emails are being sent from your _production_ environment. You can do this by testing that the ***Lost password*** form available at `/Security/lostpassword` sends an email to your inbox, or with the following code snippet that can be run via a `SilverStripe\Dev\BuildTask`:

```php
$email = new SilverStripe\Control\Email\Email('no-reply@mydomain.com', 'myuser@gmail.com', 'My test subject', 'My email body text');
$email->send();
```

Using the code snippet above also tests that the ability to set the "from" address is working correctly.

See the [email section](/developer_guides/email) for further details, including how to set the administrator "from" email address, change the `sendmail` binary location and how to use SMTP or other mail transports instead of sendmail.


## PHP Requirements for older Silverstripe CMS releases {#php-support}

Silverstripe CMS's PHP support has changed over time and if you are looking to upgrade PHP on your Silverstripe CMS site, this
table may be of use:

| Silverstripe CMS Version | PHP Version | More information |
| -------------------- | ----------- | ---------------- |
| 3.0 - 3.5            | 5.3 - 5.6   | |
| 3.6                  | 5.3 - 7.1   | |
| 3.7                  | 5.3 - 7.4   | [changelog](https://docs.silverstripe.org/en/3/changelogs/3.7.4/) |
| 4.0 - 4.4            | 5.6+        | |
| 4.5 - 4.9            | 7.1+        | [blog post](https://www.silverstripe.org/blog/our-plan-for-ending-php-5-6-support-in-silverstripe-4/) |
| 4.10                 | 7.3+        | [changelog](/Changelogs/4.10.0#phpeol/) |
| 4.11 +               | 7.4+        | [changelog](/Changelogs/4.11.0#phpeol) |

## CMS browser requirements

Silverstripe CMS supports the following web browsers:

* Google Chrome
* Microsoft Edge
* Mozilla Firefox

We aim to provide satisfactory experiences in Apple Safari. Silverstripe CMS works well across Windows, Linux, and Mac
operating systems.

## End user requirements

Silverstripe CMS is designed to make excellent, standards-compliant websites that are compatible with a wide range of
industry standard browsers and operating systems. A competent developer is able to produce websites that meet W3C
guidelines for HTML, CSS, JavaScript, and accessibility, in addition to meeting specific guide lines, such as
e-government requirements.