mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-08 18:51:12 +02:00
328 lines
19 KiB
Markdown
328 lines
19 KiB
Markdown
---
|
|
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.
|