mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
DOCS Rewrite server requirements
* Remove overly specific PHP RNG instructions (that's just built into PHP7 through random_bytes now, which will throw if no suitable RNG is available) * Remove PHP 5 RNG requirements, since we don't support that PHP release any mre * Remove verbose explanation of PHP 5.6 support * Remove conflicting instructions for PHP memory limits * Remove version numbers from supporetd databases other than MySQL, it's up to the community modules to define that * Remove Oracle support (code is nine years old!) * Make "community supported" status clearer on databases, people can draw their own conclusions as open source users on Github * Remove IIS version number, I think we should just stick to "needs web.config" and not give the impression that this is actively tested * Remove mention of OSes for web servers, that's kind of irrelevant in today's hosting world (containers, PaaS, etc) * Shorten install instructions in favour of a "quickstart" and point to lessons instead * Remove mention of archive download option, we really shouldn't promote this - composer is the de-facto standard * Add generic descriptions of the hosting environment considerations without going too much into specifics * Remove Apache version number, we don't test on different versions, and really mostly rely on mod_rewrite working properly. Laravel does the same (doesn't claim specific Apache version support)
This commit is contained in:
Ingo Schommer
parent
d77c6514b4
commit
ca5b1cbf61
@ -4,56 +4,121 @@ SilverStripe CMS needs to be installed on a web server. Content authors and webs
|
||||
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.
|
||||
|
||||
Our web-based [PHP installer](installation/) can check if you meet the requirements listed below.
|
||||
## PHP
|
||||
|
||||
## Web server software requirements
|
||||
* PHP >=7.1
|
||||
* 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`)
|
||||
|
||||
SilverStripe 4.5 has the following server requirements:
|
||||
Our web-based [PHP installer](installation/) can check requirements.
|
||||
Use [phpinfo()](http://php.net/manual/en/function.phpinfo.php) to inspect your configuration.
|
||||
|
||||
* PHP 7.1+ (5.6+ was supported 4.0 - 4.4, we dropped support for these 6 months after PHP EOL'd them)
|
||||
* Allocate at least 48MB of memory to each PHP process. (SilverStripe can be resource hungry for some intensive operations.)
|
||||
* PHP requires a suitable CSPRNG (random number generator) source for generating random tokens, password salts etc. This can be any of the following, and most operating systems will have at least one source available:
|
||||
* PHP 7 `random_bytes()`:
|
||||
* `CryptGenRandom` (Windows only)
|
||||
* `arc4random_buf` (OpenBSD & NetBSD only)
|
||||
* `getrandom(2)` (Linux only)
|
||||
* `/dev/urandom`
|
||||
* PHP 5 [`random_compat`](https://github.com/paragonie/random_compat) polyfill:
|
||||
* libsodium
|
||||
* `/dev/urandom`
|
||||
* [`mcrypt_create_iv()`](http://php.net/manual/en/function.mcrypt-create-iv.php)
|
||||
* CAPICOM Utilities (`CAPICOM.Utilities.1`, Windows only)
|
||||
* Required modules: ctype, dom, fileinfo, hash, intl, mbstring, session, simplexml, tokenizer, xml.
|
||||
* At least one from each group of extensions:
|
||||
* Image library extension (gd2, imagick)
|
||||
* DB connector library (pdo, mysqli, pgsql)
|
||||
* Recommended configuration
|
||||
* Dev (local development for running test framework): memory_limit 512MB
|
||||
* Production: memory_limit = 64M
|
||||
## Database
|
||||
|
||||
* See [phpinfo()](http://php.net/manual/en/function.phpinfo.php) for more information about your environment
|
||||
* One of the following databases:
|
||||
* MySQL 5.6+
|
||||
* PostgreSQL 9.4+ (requires ["silverstripe/postgresql" module](http://silverstripe.org/postgresql-module))
|
||||
* Warning: PostgreSQL has some known issues with collations when installed on Alpine, MacOS X and BSD derivatives
|
||||
(see [PostgreSQL FAQ](https://wiki.postgresql.org/wiki/FAQ#Why_do_my_strings_sort_incorrectly.3F)).
|
||||
We do not support such installations, although they still may work correctly for you.
|
||||
As a workaround for PostgreSQL 10+ you could manually switch to ICU collations (e.g. und-x-icu).
|
||||
There are no known workarounds for PostgreSQL <10.
|
||||
* [SQL Server](http://silverstripe.org/microsoft-sql-server-database/),
|
||||
[Oracle](https://github.com/smindel/silverstripe-oracle) and
|
||||
[SQLite](http://silverstripe.org/sqlite-database/) are not commercially supported, but are under development by our open source community.
|
||||
* One of the following web server products:
|
||||
* Apache 2.0+ with mod_rewrite and "AllowOverride All" set
|
||||
* IIS 7+
|
||||
* Support for Lighttpd, IIS 6, and other web servers may work if you are familiar with configuring those products.
|
||||
* We recommend enabling content compression (for example with mod_deflate) to speed up the delivery of HTML, CSS, and JavaScript.
|
||||
* One of the following operating systems:
|
||||
* Linux/Unix/BSD
|
||||
* Windows
|
||||
* Mac OS X
|
||||
* 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)
|
||||
|
||||
## Webserver Configuration
|
||||
|
||||
### PHP Requirements for older SilverStripe releases
|
||||
### Overview
|
||||
|
||||
SilverStripe needs to handle a variety of HTTP requests,
|
||||
and relies on the hosting environment to be configured securely to
|
||||
enforce restrictions. There are secure default in place for Apache,
|
||||
but you should be aware of the configuration regardless of your webserver setup.
|
||||
|
||||
### Filesystem permissions
|
||||
|
||||
SilverStripe needs write access for the webserver user to `public/assets`,
|
||||
and read access for that user on everything else in your webroot.
|
||||
|
||||
### Assets
|
||||
|
||||
SilverStripe 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)).
|
||||
|
||||
### 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.
|
||||
|
||||
### URL Rewriting
|
||||
|
||||
SilverStripe 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 can add HTTP headers to reponses 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.
|
||||
|
||||
### Symlinks
|
||||
|
||||
SilverStripe 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 pulled over to the `public/` folder automatically.
|
||||
If the filesystem supports it, this is achieved through symlinks.
|
||||
Depending on your hosting and deployment mechanisms,
|
||||
you might want to enforce copying files instead.
|
||||
See [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin) for details.
|
||||
|
||||
### 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 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
|
||||
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)
|
||||
* [Mac OSX with Homebrew](https://forum.silverstripe.org/t/installing-on-osx-with-homebrew/2247)
|
||||
* [MAC OSX 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)
|
||||
|
||||
## PHP Requirements for older SilverStripe releases {#php-support}
|
||||
|
||||
SilverStripe's PHP support has changed over time and if you are looking to upgrade PHP on your SilverStripe site, this table may be of use:
|
||||
|
||||
@ -66,26 +131,13 @@ SilverStripe's PHP support has changed over time and if you are looking to upgra
|
||||
| 4.5+ (unreleased) | 7.1+ | [blog post](https://www.silverstripe.org/blog/our-plan-for-ending-php-5-6-support-in-silverstripe-4/) |
|
||||
|
||||
|
||||
## Web server hardware requirements
|
||||
|
||||
Hardware requirements vary widely depending on the traffic to your website, the complexity of its logic (i.e., PHP), and
|
||||
its size (i.e., database.) By default, all pages are dynamic, and thus access both the database and execute PHP code to
|
||||
generate. SilverStripe can cache full pages and segments of templates to dramatically increase performance.
|
||||
|
||||
A typical website page on a conservative single CPU machine (e.g., Intel 2Ghz) takes roughly 300ms to generate. This
|
||||
comfortably allows over a million page views per month. Caching and other optimisations can improve this by a factor of
|
||||
ten or even one hundred times. SilverStripe CMS can be used in multiple-server architectures to improve scalability and
|
||||
redundancy.
|
||||
|
||||
For more information on how to scale SilverStripe see the [Performance](/developer_guides/performance/) Guide.
|
||||
|
||||
## Client side (CMS) browser requirements
|
||||
## CMS browser requirements
|
||||
|
||||
SilverStripe CMS supports the following web browsers:
|
||||
* Google Chrome
|
||||
* Internet Explorer 11
|
||||
* Microsoft Edge
|
||||
* Mozilla Firefox.
|
||||
* Mozilla Firefox
|
||||
|
||||
We aim to provide satisfactory experiences in Apple Safari. SilverStripe CMS works well across Windows, Linux, and Mac operating systems.
|
||||
|
||||
|
||||
@ -1,27 +0,0 @@
|
||||
# Installation
|
||||
|
||||
These instructions show you how to install SilverStripe on any web server.
|
||||
Check out our operating system specific guides for [Linux](linux_unix),
|
||||
[Windows Server](windows) and [Mac OSX](mac_osx).
|
||||
|
||||
## Installation Steps
|
||||
|
||||
* Make sure the webserver has MySQL and PHP support (check our [server requirements](../server_requirements)).
|
||||
* Either [download the installer package](http://silverstripe.org/download), or [install through Composer](/getting_started/composer).
|
||||
* If using with the installer download, extract it into your webroot.
|
||||
* Visit your domain or IP address in your web browser.
|
||||
* You will be presented with an installation wizard asking for database and login credentials.
|
||||
* After a couple of minutes, your site will be set up. Visit your site and enjoy!
|
||||
|
||||
## Issues?
|
||||
|
||||
If the above steps don't work for any reason have a read of the [Common Problems](common_problems) section.
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
SilverStripe ships with default rewriting rules specific to your web server. Apart from
|
||||
routing requests to the framework, they also prevent access to sensitive files in the webroot,
|
||||
for example YAML configuration files. Please refer to the [secure coding](/developer_guides/security/secure_coding/#filesystem) documentation for details.
|
||||
</div>
|
||||
|
||||
## Related Lessons
|
||||
* [Up and running: Setting up a local SilverStripe dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1)
|
||||
@ -1,77 +1,53 @@
|
||||
title: Getting Started
|
||||
introduction: SilverStripe is a web application. This means that you will need to have a webserver and database. We will take you through the setup of the server environment as well the application itself.
|
||||
|
||||
## Server Requirements
|
||||
|
||||
## Installing SilverStripe
|
||||
SilverStripe requires PHP 7.1 or newer.
|
||||
It runs on many webservers and databases,
|
||||
but feels most at home running on Apache with MySQL/MariaDB.
|
||||
|
||||
The best way to get SilverStripe is to [install with Composer](composer). Composer is a package management tool for PHP that
|
||||
lets you install and upgrade SilverStripe and its modules. Although installing Composer is one extra step, it will give you much more flexibility than just downloading the file from silverstripe.org.
|
||||
If you are setting up your own environment,
|
||||
you'll need to consider a few configuration settings
|
||||
such as URL rewriting and protecting access to certain files.
|
||||
Refer to our [server requirements](server_requirements) for details.
|
||||
|
||||
Other ways to get SilverStripe:
|
||||
## Quickstart Installation
|
||||
|
||||
* If you just want to get the code as quickly as possible, you can [download SilverStripe from our website](http://www.silverstripe.org/software/download/).
|
||||
* If you already have an installed version of SilverStripe, and you haven't used Composer to get it, please see our [upgrading](/upgrading) guide. Note that [Composer](composer) provides its own tools for upgrading.
|
||||
If you're running Apache with MySQL/MariaDB already,
|
||||
and know your way around webservers, follow these steps to get started.
|
||||
SilverStripe is installed via [composer](composer), a package management tool for PHP that
|
||||
lets you install and upgrade the framework and other modules.
|
||||
Assuming you've got this tool, run the following command to install SilverStripe:
|
||||
|
||||
## Setting up a server
|
||||
```
|
||||
composer create-project silverstripe/installer my-project
|
||||
```
|
||||
|
||||
### Linux/Unix
|
||||
Within the newly created `my-project` folder, point your webserver at the `public/` folder.
|
||||
Rename `.env.example` to `.env` in your project, and configure your database connection there.
|
||||
See [environment variables](environment_management) for available configuration options,
|
||||
e.g. to configure a default CMS login via `SS_DEFAULT_ADMIN_USERNAME`.
|
||||
|
||||
To run SilverStripe on Linux/Unix, set up one of the following web servers:
|
||||
Now you should be able to build your database by running this command:
|
||||
|
||||
* [Install using Apache](installation) - our preferred platform
|
||||
* [Install using Nginx](installation/how_to/configure_nginx) - Super fast at serving static files. Great for large traffic sites.
|
||||
* [Install using nginx and HHVM](installation/how_to/setup_nginx_and_hhvm) - nginx and [HHVM](http://hhvm.com/) as a faster alternative to PHP.
|
||||
```
|
||||
vendor/bin/sake dev/build
|
||||
```
|
||||
|
||||
### Windows
|
||||
Your website should be available on your domain now (e.g. `http://localhost`).
|
||||
The CMS login can be accessed at `/admin`.
|
||||
|
||||
The most straightforward way to get SilverStripe running on Windows is with the [Microsoft Web Platform installer](installation/other_installation_options/windows_platform_installer). You can skip the "getting the code" step.
|
||||
## Guided Installation
|
||||
|
||||
For more flexibility, you can set up either of the following web servers, and use Composer to get the code:
|
||||
If you are unsure on how this all works, or prefer to follow
|
||||
an installer wizard, please jump on our [lessons](https://www.silverstripe.org/learn/lessons/v4/).
|
||||
Webserver setup is covered in
|
||||
[Lesson 4: Setting up a local dev environment](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1)
|
||||
|
||||
* [Install using IIS](installation/other_installation_options/windows_iis7)
|
||||
* [Install using Apache/WAMP](installation/windows)
|
||||
|
||||
### Mac OS X
|
||||
|
||||
Mac OS X comes with a built-in webserver, but there are a number of other options:
|
||||
|
||||
* [Install using MAMP](installation/mac_osx)
|
||||
* [Install using Homebrew](installation/other_installation_options/mac_osx_homebrew)
|
||||
|
||||
### Virtual Machines through Vagrant
|
||||
|
||||
[Vagrant](https://www.vagrantup.com/) creates portable development environments
|
||||
which can be hosted on Linux, Windows and Mac OS X. The virtual machine
|
||||
usually runs a flavour of Linux. As a self-contained pre-configured environment,
|
||||
getting up an running with Vagrant tends to be easier than creating a complete
|
||||
development environment from scratch on your own machine.
|
||||
|
||||
* [silverstripe-australia/vagrant-environment](https://github.com/silverstripe-australia/vagrant-environment)
|
||||
* [BetterBrief/vagrant-skeleton](https://github.com/BetterBrief/vagrant-skeleton)
|
||||
|
||||
Note: These instructions are supported by the community.
|
||||
|
||||
## Virtual Machines through Bitnami
|
||||
|
||||
[Bitnami](https://bitnami.com) is an online service that makes it easy to get
|
||||
apps running on cloud providers like Amazon Web Services as well as local
|
||||
virtualised environments. Bitnami has a [SilverStripe Virtual Machine](https://bitnami.com/stack/silverstripe/virtual-machine)
|
||||
ready for download or installation on a cloud platform.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into trouble, see [common-problems](installation/common_problems) or
|
||||
If you run into trouble, see [common-problems](common_problems) or
|
||||
check our [community help options](https://www.silverstripe.org/community/).
|
||||
|
||||
|
||||
## Related Lessons
|
||||
* [Up and running](https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1)
|
||||
* [Creating your first project](https://www.silverstripe.org/learn/lessons/v4/creating-your-first-project)
|
||||
* [Migrating static templates into your theme](https://www.silverstripe.org/learn/lessons/v4/migrating-static-templates-into-your-theme-1)
|
||||
* [Working with multiple templates](https://www.silverstripe.org/learn/lessons/v4/working-with-multiple-templates-1)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
* [Module installation](/developer_guides/extending/modules)
|
||||
|
||||
|
||||
|
||||
@ -26,5 +26,5 @@ introduction: The lessons take a step by step look at how to build a SilverStrip
|
||||
|
||||
## Help: If you get stuck
|
||||
|
||||
* [Common Problems](/getting_started/installation/common_problems): Review some existing solutions to common problems.
|
||||
* [Common Problems](/getting_started/common_problems): Review some existing solutions to common problems.
|
||||
* [SilverStripe Community](http://www.silverstripe.org/community/): Join our community chat via Slack, or ask a question on Stack Overflow.
|
||||
|
||||
@ -46,7 +46,8 @@ SilverStripe projects should not track the "resources" directory in their source
|
||||
|
||||
### Exposing assets in the web root
|
||||
|
||||
SilverStripe projects ship with `silverstripe/vendor-plugin`. This Composer plugin automatically tries to expose assets from your project and installed modules after installation, or after an update.
|
||||
SilverStripe projects ship with [silverstripe/vendor-plugin](https://github.com/silverstripe/vendor-plugin).
|
||||
This Composer plugin automatically tries to expose assets from your project and installed modules after installation, or after an update.
|
||||
|
||||
Developers can explicitly expose static assets by calling `composer vendor-expose`. This is necessary after updating your `resources-dir` or `expose` configuration in your `composer.json` file.
|
||||
|
||||
|
||||
@ -314,7 +314,7 @@ to put protected files into `/sites/myapp/protected` with the below `.env` setti
|
||||
SS_PROTECTED_ASSETS_PATH="/sites/myapp/protected"
|
||||
```
|
||||
|
||||
### Configuring: File types
|
||||
### Configuring: File types {#file-types}
|
||||
|
||||
In addition to configuring file locations, it's also important to ensure that you have allowed the
|
||||
appropriate file extensions for your instance. This can be done by setting the `File.allowed_extensions`
|
||||
|
||||
@ -752,7 +752,7 @@ Public files have a "canonical URL" which doesn't change when file contents are
|
||||
See our ["File Management" guide](/developer_guides/files/file_management) for more information.
|
||||
|
||||
Depending on your server configuration, it may also be necessary to adjust your assets folder
|
||||
permissions. Please see the [common installation problems](/getting_started/installation/common_problems)
|
||||
permissions. Please see the [common installation problems](/getting_started/common_problems)
|
||||
guide for configuration instruction.
|
||||
|
||||
### Image handling {#image-handling}
|
||||
@ -1089,7 +1089,7 @@ You will need to make sure that these files are writable via the web server, and
|
||||
configuration customisation is done via overriding these templates.
|
||||
|
||||
Depending on your server configuration, it may also be necessary to adjust your assets folder
|
||||
permissions. Please see the [common installation problems](/getting_started/installation/common_problems)
|
||||
permissions. Please see the [common installation problems](/getting_started/common_problems)
|
||||
guide for configuration instruction.
|
||||
|
||||
If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user