tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #9212 from open-sausages/pulls/4/docs-requirements

Browse Source 
DOCS Rewrite server requirements and install docs
This commit is contained in:
Garion Herman 2019-09-05 16:02:23 +12:00 committed by GitHub
commit 1b94131cad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 160 additions and 1300 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
docs/en/00_Getting_Started/00_Server_Requirements.md
View File

@ -4,56 +4,130 @@ 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 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. 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) ## Database
* 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
* See [phpinfo()](http://php.net/manual/en/function.phpinfo.php) for more information about your environment * MySQL >=5.6 (built-in, [commercially supported](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/))
* One of the following databases: * PostgreSQL ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/postgresql), community supported)
* MySQL 5.6+ * SQL Server ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/mssql), community supported)
* PostgreSQL 9.4+ (requires ["silverstripe/postgresql" module](http://silverstripe.org/postgresql-module)) * SQLite ([third party module](https://addons.silverstripe.org/add-ons/silverstripe/sqlite3), community supported)
* 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)). ## Webserver Configuration
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
### 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 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 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
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 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.
### 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)
* [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)
## 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: 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 +140,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/) | | 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 ## CMS browser 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
SilverStripe CMS supports the following web browsers: SilverStripe CMS supports the following web browsers:
* Google Chrome * Google Chrome
* Internet Explorer 11 * Internet Explorer 11
* Microsoft Edge * 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. We aim to provide satisfactory experiences in Apple Safari. SilverStripe CMS works well across Windows, Linux, and Mac operating systems.

24
docs/en/00_Getting_Started/01_Installation/01_Linux_Unix.md
View File

@ -1,24 +0,0 @@
# Installation on Linux, Unix and *nix like Operating Systems
SilverStripe should be able to be installed on any Linux, Unix or *nix like OS as long as the correct server software is installed and configured (referred to as *nix in this document from herein). It is common that web hosting that you may use for your production SilverStripe application will be *nix based, here you may also want to use *nix locally to ensure how you develop locally mimics closely your production environment.
Is important to ensure you check the [Server Requirements](/getting_started/server_requirements) list before acquiring and installing SilverStripe on your *nix server (locally or otherwise).
At a high level you will need a:
* Web server e.g. Apache, Nginx
* Database e.g. MariaDB, Postgres, MySQL
* PHP
##*nix installation guides on the web
There are a number of good step by step guides covering server setups and installing of SilverStripe on the various flavours of *nix systems.
Note: Many of the following guides simply download SilverStripe as a zipped file. We recommend the use of [Composer](/getting_started/composer/) once you get to the point of installing SilverStripe (though the choice is up to you). Always ensure you get the latest version if you are starting a new project.
###Known (but not exhaustive) list
* [How To Install Silverstripe on Your VPS](https://www.digitalocean.com/community/tutorials/how-to-install-silverstripe-on-your-vps)
* [Running SilverStripe On Nginx (LEMP) On Debian Wheezy/Ubuntu 13.04](http://www.howtoforge.com/running-silverstripe-on-nginx-lemp-on-debian-wheezy-ubuntu-13.04)
* [Setting up nginx, PHP-FPM, and SilverStripe on Fedora 19](http://halkyon.net/blog/setting-up-nginx-php-fpm-and-silverstripe-installation-on-fedora-19/)
* [How to install SilverStripe CMS on a Linux Virtual Server](http://www.rosehosting.com/blog/how-to-install-silverstripe-cms-on-a-linux-virtual-server/)
_If you find further good *nix related installation articles please email these to community+docs@silverstripe.org._

49
docs/en/00_Getting_Started/01_Installation/02_Mac_OSX.md
View File

@ -1,49 +0,0 @@
# Mac OSX with MAMP
This topic covers setting up your Mac as a web server and installing SilverStripe.
OSX comes bundled with PHP and Apache, but you're stuck with the versions it ships with.
It is also a bit harder to install additional PHP modules required by SilverStripe.
[MAMP](http://www.mamp.info/en/) is a simple way to get a complete webserver
environment going on your OSX machine, without removing or altering any system-level configuration.
Check out the [MAC OSX with Homebrew](/getting_started/installation/other_installation_options/mac_osx_homebrew)
for an alternative, more configurable installation process.
## Requirements
Please check the [system requirements](http://www.mamp.info/en/documentation/) for MAMP,
you'll need a fairly new version of OSX to run it.
## MAMP Installation
* [Download MAMP](http://www.mamp.info/en/)
* Install and start MAMP
* Check out your new web server environment on `http://localhost:8888`
## SilverStripe Installation
[Composer](http://getcomposer.org) is a dependancy manager for PHP, and the preferred way to
install SilverStripe. It ensures that you get the correct set of files for your project.
Composer uses your MAMP PHP executable to run and also requires [git](http://git-scm.com)
to automatically download the required files from GitHub and other repositories.
In order to install Composer, we need to let the system know where to find the PHP executable.
Open or create the `~/.bash_profile` file in your home folder, then add the following line:
`export PATH=/Applications/MAMP/bin/php/php7.0.20/bin:$PATH`
You'll need to adjust the PHP version number (`php7.0.20`). The currently running PHP version is shown on `http://localhost:8888/MAMP/index.php?page=phpinfo`.
Run `source ~/.bash_profile` for the changes to take effect. You can verify that the correct executable
is used by running `which php`. It should show the path to MAMP from above.
Now you're ready to install Composer: Run `curl -sS https://getcomposer.org/installer | php`.
We recommend that you make the `composer` executable available globally,
which requires moving the file to a different folder. Run `mv composer.phar /usr/local/bin/composer`.
More detailed installation instructions are available on [getcomposer.org](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx).
You can verify the installation by typing the `composer` command, which should show you a command overview.
Finally, we're ready to install SilverStripe through composer:
`composer create-project silverstripe/installer /Applications/MAMP/htdocs/silverstripe/`.
After finishing, the installation wizard should be available at `http://localhost:8888/silverstripe`.
The MAMP default database credentials are user `root` and password `root`.
We have a separate in-depth tutorial for [Composer Installation and Usage](/getting_started/composer).

77
docs/en/00_Getting_Started/01_Installation/03_Windows.md
View File

@ -1,77 +0,0 @@
# Windows with WAMPServer 2.5+
An easy and reliable approach to getting SilverStripe running on Windows is to use Apache, which can be conveniently
done through [WampServer](http://www.wampserver.com/en/). This can be useful if you are deploying on Linux Apache and
want a Microsoft Windows machine with a very similar environment.
## Install WAMP
1. Go to the [WampServer download page](http://www.wampserver.com/en/#download-wrapper).
2. You will first need to download and install the suggested [Visual C++ Redistributable for Visual Studio 2012 Update 4](http://www.microsoft.com/en-us/download/details.aspx?id=30679#) BEFORE installing WampServer.
3. Next, download the WampServer installer and the run the installer. By default, it will install to C:\wamp. You can choose your own install path if you wish; however note we will refer to the c:/wamp in the test of this tutorial.
4. Once WampServer has been installed and launched, you will see a small "W" in the task bar, next to
the clock. If everything is working, then it will be green. If it's orange or red, then something is likely misconfigured. See the Troubleshooting section below. If you can't see the "W", then WampServer hasn't been started and you should start WampServer from the start menu.
5. Left-click the "W", then select Apache -> Apache Modules -> Rewrite Module. The "W" will flick to orange, and
then return to green.
6. Left-click the "W", then select MySQL -> my.ini. At the very bottom of the file, and add the following to a new line without the quotes): "lower_case_table_names = 2". Save the file, close Notepad and left-click the "W", and
select 'Restart all services'. This is used to ease the transition between a Windows-based install and a Linux-based
install where database case-sensitivity is important.
## Install SilverStripe
### Composer
Composer is becoming our preferred way to manager installation and future dependancy management of SilverStripe modules. Getting started with Composer requires:
1. PHP installed on your local environment (which in this context is part of WAMP).
2. The Composer application itself (there is a Windows installer which will ask you to point it to PHP, in this case it should be at C:/wamp/bin/php/phpX.X.X/php.exe).
See the [Composer documentation](https://getcomposer.org/doc/00-intro.md#installation-windows) to get the installer.
3. A command line such as windows command prompt or [gitbash](http://git-scm.com/download/win) (recommended and comes as part of git for windows).
Once you have installed the above, open a command line and use the following command to get a fresh copy of SilverStripe stable code installed into a 'silverstripe' sub-folder (note here we are using gitbash paths).
```bash
$ cd /c/wamp/www
$ composer create-project silverstripe/installer ./silverstripe
```
### Zip download
* [Download](http://silverstripe.org/stable-download) the latest SilverStripe CMS and Framework package
* Unpack the archive into `C:\wamp\www`
* Rename the unpacked directory from `C:\wamp\www\silverstripe-vX.X.X` to `C:\wamp\www\silverstripe`
## Install and configure
* Option 1: Environment file - Set up a file named `.env` file either in the webroot and setup as per the [Environment Management process](/getting_started/environment_management).
* Option 2: Installer - Visit `http://localhost/silverstripe/public` - you will see SilverStripe's installation screen.
* You should be able to click "Install SilverStripe" and the installer will do its thing. It takes a minute or two.
* Once the installer has finished, visit `http://localhost/silverstripe/public`. You should see your new SilverStripe site's
home page.
## Troubleshooting
1. If there is some misconfiguration, this often indicated you may have another service on port 80 or port 3306. Here are some common sources of problems to check.
After correcting these issues, left-click the "W" and choose 'restart all services'. It might a short while to restart, but the "W" turn green.
* You might have IIS running. Check Start -> Control Panel -> Administrative Tools -> Internet Information
Services. Ensure that any web site services are stopped.
* If you run Skype, visit Select "Tools" -> "Options" in Skype's menu. Find an option "Use port 80 and 443 as
alternatives for incoming connection". Make sure that it is de-selected.
2. Vista's security controls can cause issues. If you have installed on Vista but you're getting errors, there is a chance that SilverStripe does not have sufficient permissions.
Right clicked on the installation folder and go to Permissions > Security > Users > Advanced and give the user full
control.
3. Apache rewrite (mod_rewrite) isn't working and it's installed (prior to SilverStripe 3.1.11)
Due to some changes to `mod_dir` in [Apache 2.4](http://httpd.apache.org/docs/current/mod/mod_dir.html#DirectoryCheckHandler) (precedence of handlers),
index.php gets added to the URLs as soon as you navigate to the homepage of your site.
To fix this place the following within the `mod_rewrite` section of your .htaccess file:
```
<IfModule mod_rewrite.c>
# Turn off index.php handling requests to the homepage fixes issue in apache >=2.4
<IfModule mod_dir.c>
DirectoryIndex disabled
</IfModule>
# ------ #
</IfModule>
```

118
docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Mac_OSX_Homebrew.md
View File

@ -1,118 +0,0 @@
# Mac OSX with Homebrew
This topic covers setting up your Mac as a web server and installing SilverStripe.
OSX comes bundled with PHP, but you're stuck with the version and modules it ships with.
If you run projects on different PHP versions, or care about additional PHP module support
and other dependencies such as MariaDB, we recommend an installation through [Homebrew](http://brew.sh/).
Check out the [MAC OSX with MAMP](/getting_started/installation/mac_osx) for an alternative installation process
which packages up the whole environment into a convenient application.
## Requirements
Since we're compiling PHP, some build tooling is required.
Run the following command to install Xcode Command Line Tools.
xcode-select --install
Now you can install Homebrew itself:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
## Install PHP
First we're telling Homebrew about some new repositories to get the PHP installation from:
brew tap homebrew/dupes
brew tap homebrew/php
We're installing PHP 5.6 here, with the required `intl` module:
brew install php56 php56-intl php56-apcu
There's a [Homebrew Troubleshooting](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Troubleshooting.md) guide if Homebrew doesn't work out as expected (run `brew update` and `brew doctor`).
Have a look at the [brew-php-switcher](https://github.com/philcook/brew-php-switcher)
project to install multiple PHP versions in parallel and switch between them easily.
## Install the Database (MariaDB/MySQL)
brew install mariadb
unset TMPDIR
mysql_install_db --user=`whoami` --basedir="$(brew --prefix mariadb)" --datadir=/usr/local/var/mysql --tmpdir=/tmp
mysql.server start
'/usr/local/opt/mariadb/bin/mysql_secure_installation'
To start the database server on boot, run the following:
ln -sfv /usr/local/opt/mariadb/*.plist ~/Library/LaunchAgents
You can also use `mysql.server start` and `mysql.server stop` on demand.
## Configure PHP and Apache
We're not installing Apache, since OSX already ships with a perfectly fine installation of it.
Edit the existing configuration at `/etc/apache2/httpd.conf`,
and uncomment/add the following lines to activate the required modules:
LoadModule rewrite_module libexec/apache2/mod_rewrite.so
LoadModule php5_module /usr/local/opt/php55/libexec/apache2/libphp5.so
Change the `DocumentRoot` setting to your user folder (replacing `<user>` with your OSX user name):
DocumentRoot "/Users/<user>/Sites"
Now find the section starting with `<Directory "/Library/WebServer/Documents">` and change it as follows,
again replacing `<user>` with your OSX user name:
<Directory "/Users/<user>/Sites">
Options FollowSymLinks Multiviews
MultiviewsMatch Any
AllowOverride All
Require all granted
</Directory>
We also recommend running the web server process with your own user on a development environment,
since it makes permissions easier to handle when running commands both
from the command line and through the web server. Find and adjust the following options,
replacing the `<user>` placeholder:
user <user>
Group staff
Now start the web server:
sudo apachectl start
Every configuration change requires a restart:
sudo apachectl restart
You can also load this webserver on boot:
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist
After starting the webserver, you should see a simple "Forbidden" page generated by Apache
when accessing `http://localhost`.
## SilverStripe Installation
[Composer](http://getcomposer.org) is a dependancy manager for PHP, and the preferred way to
install SilverStripe. It ensures that you get the correct set of files for your project.
Composer uses the PHP executable we've just installed. It also needs [git](http://git-scm.com)
to automatically download the required files from GitHub and other repositories.
Run `curl -sS https://getcomposer.org/installer | php` to install the `composer` executable.
We recommend that you make the executable available globally,
which requires moving the file to a different folder. Run `mv composer.phar /usr/local/bin/composer`.
More detailed installation instructions are available on [getcomposer.org](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx).
You can verify the installation by typing the `composer` command, which should show you a command overview.
Finally, we're ready to install SilverStripe through composer:
`composer create-project silverstripe/installer /Users/<user>/Sites/silverstripe/`.
After finishing, the installation wizard should be available at `http://localhost/silverstripe`.
The Homebrew MariaDB default database credentials are user `root` and password `root`.
We have a separate in-depth tutorial for [Composer Installation and Usage](/getting_started/composer).

221
docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Vagrant_Virtualbox.md
View File

@ -1,221 +0,0 @@
# Install SilverStripe using Vagrant
This guide steps through installing a virtual machine on your chosen virtual platform.
This guide will work for:
- Virtualbox
- Parallels
This guide may work for:
- VMWare
Vagrant has all server settings stored in a Vagrantfile which is a text file containing the commands and settings needed to setup a webserver. This is ideal for version control, which helps distribution and sharing between team members.
## Requirements
This can be used with many modern computers, this can be done on Windows, Mac or Linux operating systems. We recommend a relatively strong computer that can handle a virtual machine in the background.
- Minimum memory would be 4GB of RAM
- Roughly 20GB Harddrive space (depends on which box you choose to use)
- Software to install beforehand:
- [Vagrant](http://www.vagrantup.com/downloads)
- [Virtualbox](https://www.virtualbox.org/wiki/Downloads)
- Installing SilverStripe by [Composer](https://getcomposer.org/download/) or download the [ZIP file](https://www.silverstripe.org/download/).
*Important*: It is strongly advised to have a fast and wired internet connection when running initial the setup, as there is a lot of downloading required.
Vagrant downloads and sets up an entire operating system.
## Setting it up
Most of this requires using only the command line and text editor or IDE.
Create a folder where your vagrant will be in and browse to the folder in the command line:
```bash
mkdir virtuallythere
cd virtuallythere
```
### Creating the Vagrantfile
Create/Browse to the folder you’ll be developing in:
```bash
vagrant init
```
In its current state, you could start the vagrant machine and it will run, but you won't be able to do much with it yet.
### Setting the box
Open the `Vagrantfile` that was created in your vagrant folder with your preferred text editor.
Look for the line which describes the box you are going to use:
```ruby
config.vm.box = "base"
```
This defines what pre-built Operating System the vagrant machine will be using. We'll be changing `base` to something closer to what we’d like, perhaps similar to your production server, you can find a range of boxes [listed here](https://app.vagrantup.com/boxes/search)
We've chosen to use `RHEL7.0`, but you can easily change it to suit your needs.
```ruby
config.vm.box = "box-cutter/centos73"
```
*Important*: Because this is redhat, the shell commands used later on will be using `yum install` instead of `apt-get install` for Debian based boxes.
### The private network and hostname
Now we’ll add the vagrant machine to our computer’s private network, this will mean no one outside this computer will be able to access it without some special setup.
So this will be your own development environment!
To do that, look for this line:
```ruby
# config.vm.network "private_network", ip: "192.168.33.10"
```
First we’ll need to uncomment it, so delete only the `#` at the start of the line, then add a hostname IP address of your choice to use.
```ruby
config.vm.hostname = "virtuallythere.dev"
config.vm.network "privatenetwork", ip: "10.1.2.50"
```
### Syncing files
Next we’ll sync our website folder to the virtual machine, so it has the files needed to run SilverStripe. There are many different ways to do this, depending on your own preferences and possibly different boxes.
To keep things simple, we’re going to sync our vagrant folder to the virtual machine, so everything in your vagrant folder will be visible to the virtual machine.
Find this line:
```ruby
config.vm.synced_folder "../data", "/vagrant_data"
```
Then change to match this:
```ruby
config.vm.synced_folder ".", "/vagrant"
```
### Setting resources
This step is optional, but it is recommended to configure the virtual machine resources allocated to it, so it doesn’t take more resources than it should, something like this should be enough to start with:
```ruby
config.vm.provider "virtualbox" do |vb|
vb.memory = "1024"
vb.name = "virtuallythere"
end
```
*Important*: This is for Virtualbox again, change “virtualbox” to the virtual platform that you are using, you might need to make sure the setting `vb.memory` is supported by the platform you’re using because it may be different.
### Script to setup server
Now we need to setup our environment using shell scripts, this will install software that you need for your server to be working and usable. You could even customise the setup to be closer like your production server.
For now find these lines:
```ruby
# config.vm.provision "shell", inline: <<-SHELL
# sudo apt-get update
# sudo apt-get install -y apache2
# SHELL
```
And modify it to call a shell script in your vagrant folder:
```ruby
config.vm.provision "shell", path: "setup.sh"
```
*Important*: We’re using shell script because we’re using a Linux server, please use the scripting language that your server environment supports.
Now to create the `setup.sh` file. This script will setup `php+modules`, `mariadb/mysql` and `apache`, the ones I had listed is the minimal required to get SilverStripe started and working out of the box.
```bash
yum update -y --disableplugin=fastestmirror
systemctl restart sshd
yum install -y httpd httpd-devel mod_ssl
yum -y install php php-common php-mysql php-pdo php-intl php-gd php-xml php-mbstring
echo "Include /vagrant/apache/*.conf" >> /etc/httpd/conf/httpd.conf
echo "date.timezone = Pacific/Auckland" >> /etc/php.ini
systemctl start httpd.service
systemctl enable httpd.service
yum install -y mariadb-server mariadb
systemctl start mariadb.service
systemctl enable mariadb.service
```
*Important*: Again, as noted above, this uses RHEL so `yum install` is used, please remember to change to `apt-get install` or other packaging tool as necessary.
Save `setup.sh` in the same folder as your Vagrantfile.
### Setting up Apache
If you inspect the script I’ve included above, you’ll notice this line:
```bash
echo "Include /vagrant/apache/*.conf" >> /etc/httpd/conf/httpd.conf
```
This will allow us to customise our apache, particularly the VirtualHost part
Earlier in the post, I had defined a hostname:
```ruby
config.vm.hostname = "virtuallythere.dev"
```
We’ll need to create a conf file for this hostname in a apache folder, create the folder first:
```bash
mkdir apache
```
We'll save a `vagrant.conf` file in the newly created apache folder, and inside we’ll define the VirtualHost:
```apache
ServerRoot "/etc/httpd"
<Directory />
AllowOverride none
Require all denied
</Directory>
DocumentRoot "/vagrant/public"
<Directory "/vagrant/public">
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
<VirtualHost *:80>
ServerName virtuallythere.dev
ServerAlias www.virtuallythere.dev
DocumentRoot /vagrant/public
LogLevel warn
ServerSignature Off
<Directory /vagrant/public>
Options +FollowSymLinks
Options -ExecCGI -Includes -Indexes
AllowOverride all
Require all granted
</Directory>
# SilverStripe specific
<LocationMatch assets/>
php_flag engine off
</LocationMatch>
</VirtualHost>
```
### Download SilverStripe
Last step is to download SilverStripe for the virtual machine to use, if you have an existing SilverStripe installation you could also move everything to this folder instead of downloading a new installation to the public folder.
As mentioned above, you could install SilverStripe by [Composer](https://getcomposer.org/download/) or download the [ZIP file](https://www.silverstripe.org/download/).
### We’re ready for launch
That’s all! When that’s done, run:
```bash
vagrant up
```
If you've been following this guide, you can browse to http://virtuallythere.dev/install if you are using a new installation, or go to http://virtuallythere.dev if you are using an existing SilverStripe installation. If you've modified the hostname, follow the new hostname you've chosen.
### Last step
Version control this and share it with your teammates!
All they need is listed in the Requirements at the top, and the files you’ve just created:
- Vagrantfile
- setup.sh
- apache/virtuallythere.conf
- public/ _(with SilverStripe files here)_
## Advanced tasks
Once you get started with Vagrant, it’s very easy to improve and tweak things further if you needed. With version control, if you've made a mistake, you can easily rollback to the last working version.
Some examples of things you could do:
- You could have multiple hostnames for the same virtual machine by using the plugin [vagrant-hostsupdater](https://github.com/cogitatio/vagrant-hostsupdater).
- Have [multiple machines](https://docs.vagrantup.com/v2/multi-machine/) running, if you wanted to test communications between two servers
- Perhaps you have access to API server code you could host locally for development.
- [Vagrant Push](https://docs.vagrantup.com/v2/push/index.html) could be used to deploy to a Testing server.

306
docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md
View File

@ -1,306 +0,0 @@
# Install SilverStripe manually on Windows using IIS 7
This guide will step you through installing SilverStripe on Windows using IIS 7.x as the web server and SQL Server 2008 R2 as the database.
You can use this guide to install SilverStripe on the following:
* Windows Server 2008 or Windows Vista with Service Pack 2 installed
* Windows Server 2008 R2 or Windows 7
These versions of Windows will **NOT** work with this guide:
* Windows Server 2003
* Windows XP
**IMPORTANT**: Windows Server 2003 users should [follow this guide](http://doc.silverstripe.org/installation-on-windows-server-2003-iis-6) to installing SilverStripe.
The goal is to get a good working web server platform so that one or more SilverStripe projects can be easily deployed onto the server using SVN/GIT.
We'll also install SQL Server 2008 R2, and support for connecting to it in PHP.
## Requirements
* Windows Server 2008 or Windows Vista with Service Pack 2 installed
* Windows Server 2008 R2 or Windows 7
## Software to install
* Internet Information Services (IIS) 7.x
* SQL Server 2008 R2
* PHP 5.5 or newer
* SilverStripe 4
* [Microsoft URL Rewrite Module 2.0](http://www.iis.net/download/URLRewrite)
* [IIS 7 Administration Pack](http://www.iis.net/download/AdministrationPack) (ONLY required for Windows Vista or Server 2008)
* [PHP Manager](http://phpmanager.codeplex.com/releases/view/69115)
* [Microsoft Drivers for PHP for SQL Server 3.0](http://www.microsoft.com/downloads/en/details.aspx?FamilyID=80E44913-24B4-4113-8807-CAAE6CF2CA05&displaylang=en)
* [Microsoft SQL Server Native Client](http://www.microsoft.com/en-nz/download/details.aspx?id=29065) (ONLY if connecting to SQL Server from PHP)
## Install IIS
IIS 7.x comes with Windows. However, it needs to be installed. Follow these steps:
* Go to Start > Control Panel > Programs and Features
* Click **Turn Windows features on or off**. You'll find this under Tasks as a quick link
* Click **Add Roles** under the Roles Summary section when Server Manager opens
* Click Next >
* Check **Web Server (IIS)** (if a popup appears, confirm you want to proceed with the change)
* Click Next >
* Check CGI in the list - you'll find find it under Application Development
* Scroll down and check **IIS Management Scripts and Tools**
* OPTIONAL: For remote management capability, check **Management Service**
**NOTE**: These instructions are slightly different for Windows Vista and Windows 7. Instead of a Server Manager popup, you'll just get a list of features to enable. Do the same as above except click the **Internet Information Services** checkbox when the Windows Features popup appears and then expand this node and select **CGI** under World Wide Web Services > Application Development Features.
Once the installation is finished, browse to `http://localhost` in your browser. If an image pops up, then IIS has been installed correctly.
## IIS URL Rewrite Module
* Go to http://www.iis.net/extensions/URLRewrite
* Choose x86 or x64, depending on whether you installed a x86 or x64 version of Windows
* Run the downloaded file to install and enable the URL Rewrite Module
## IIS Administration Pack
**NOTE**: Windows Server 2008 R2 or Windows 7 (IIS 7.5) users can skip this step, as it's already installed!
* [Download IIS Administration Pack](http://www.iis.net/extensions/AdministrationPack)
* Run the downloaded file to enable the IIS Administration Pack (make sure it's x86 or x64 depending on your Windows version)
## SQL Server Native Client
This is only required if you're connecting to a SQL Server database.
* Go to http://www.microsoft.com/en-nz/download/details.aspx?id=29065
* Scroll down to "Native Client"
* Choose x86 or x64 depending on whether you installed a x86 or x64 version of Windows
* Run the downloaded file to install and enable the SQL Server Native Client
## Install SQL Server 2008 R2
SQL Server doesn't come with Windows. It must be separately installed.
You can use any version of SQL Server 2008 R2 or SQL Server 2008 with the latest service pack.
If you don't have a license, there's always [SQL Server 2008 R2 Express](http://www.microsoft.com/express/database/) which is feature complete, but restricted to 10GB per database.
Ensure these features are installed with your copy of SQL Server.
* SQL Server Replication
* Full-Text Search
* Management Tools
Installing SQL Server should be relatively straightforward. Keep a note of the password you create for the "sa" user. We'll need this for later when we connect to the database server via PHP to test connectivity.
### Install PHP
* Install PHP Manager from http://phpmanager.codeplex.com/releases/view/69115 (choose x86 or x64 depending on your Windows architecture)
* Download the latest stable PHP 5.5 (VC9, x86) zip from http://windows.php.net/download
* Extract zip contents to **C:\php**
* Open PHP Manager in IIS and register **C:\php\php-cgi.exe** to enable PHP for IIS
### Install SQL Server drivers for PHP
This is the PHP extension allowing it to connect to SQL Server databases.
* Download 3.0 executable from http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=20098
* Extract contents to a temporary location, such as C:\sqlsrv
* Copy **php_sqlsrv_54_nts_vc9.dll** to C:\php\ext
* Rename the file to **php_sqlsrv.dll**
* Open PHP Manager and go to **Enable or disable an extension**
* Right click **php_sqlsrv.dll** and hit **Enable**
### Install wincache extension for PHP
This is an op-code cacher which speeds up PHP execution on Windows.
* Download the latest wincache (for PHP 5.5, x86) from http://www.iis.net/download/wincacheforphp
* Extract zip contents to a temporary location, such as C:\wincache
* Copy php_wincache.dll to C:\php\ext
* Open PHP Manager and go to **Eanble or disable an extension**
* Right click **php_wincache.dll** and hit **Enable*
### Configuring PHP
* First of all, restart IIS to apply all changes
* Go to **Check phpinfo()** PHP Manager
* Ensure that **wincache** and **sqlsrv** details can be found in the information
* Go to **Enable or disable an extension** and disable everything, except for these:
php_curl.dll
php_gd2.dll
php_mbstring.dll
php_sqlsrv.dll
php_wincache.dll
php_tidy.dll
* Go to **Configure error reporting** and check **Development machine**
* Go to **Manage all settings** and set the following:
date.timezone = "Pacific/Auckland" (or choose from the list here: http://nz.php.net/manual/en/timezones.php)
post_max_size = 64M
memory_limit = 256M
upload_max_filesize = 64M
Tweak the above values as necessary if your requirements differ.
## Folder permissions for PHP
Now we need to set up folder permissions for PHP. Open the php.ini and find the paths for sessions and file uploads. They will look like this:
upload_tmp_dir="C:\Windows\Temp"
session.save_path="C:\Windows\Temp"
Two other important folders to set the permissions on are `assets` and `silverstripe-cache` (if used) in your web root.
You will need to give **Modify** permission to **IUSR** user. To do it right click the folder and choose **Properties**. Then open the security tab, press **Edit** and add the **IUSR** user to the list by clicking the **Add** button. Afterwards tick **Modify** under **Allow** for that user. Repeat these steps for each folder.
![](../../../_images/iis7-iusr-permissions.jpg)
## Install SilverStripe
Now that we've got the backend server software sorted out, it's time to install the SilverStripe CMS/framework.
Create a new file called `.env` in **C:\inetpub\wwwroot\ss**
This file tells SilverStripe projects installed on this machine which database server and credentials, as well as anything environment specific.
Inside the newly created `.env` file, insert the following code:
# What kind of environment is this: development, test, or live (ie, production)?
SS_ENVIRONMENT_TYPE="dev";
# Database connection
SS_DATABASE_SERVER="localhost"
SS_DATABASE_USERNAME="sa"
SS_DATABASE_PASSWORD=""
# Configure a default username and password to access the CMS on all sites in this environment
SS_DEFAULT_ADMIN_USERNAME="username"
SS_DEFAULT_ADMIN_PASSWORD="password"
Insert the password you created for SQL Server earlier into the **SS_DATABASE_PASSWORD** field that is currently empty.
* Grab the latest stable version from here: http://www.silverstripe.org/stable-download
* Extract contents to **C:\inetpub\wwwroot\ss**
After gettng the code installed, make sure you set the folder permissions properly (see *Folder permissions for PHP* above).
## Install the SilverStripe SQL Server module ("mssql")
* Grab the latest stable version from here: http://www.silverstripe.org/microsoft-sql-server-database/
* Extract contents to **C:\inetpub\wwwroot\ss\mssql**
## Start SilverStripe installer
Open a browser and point it to `http://localhost/ss/public`
If an installation screen shows up, congratulations! We're very close now.
Fill out the details correctly and press "Install SilverStripe".
If all goes to plan, you're done, and you should see a basic template with a few sample pages.
## Configuring PHP and IIS for production environments
**TODO**: Describe turning off PHP errors, and setting up static 404 and 500 error pages instead of giving detailed errors. Finally setting up a specific database user that isn't sa with restricted permissions.
## Troubleshooting
**Q: How do I debug the IIS 500 Server error "The FastCGI process exited unexpectedly"?**
**A:** This is a very annoying error - basically it means PHP has caused a segmentation fault, probably through itself or one of it's extensions. It's very hard to track down exactly why these errors occur, but there's a few things you can do.
Most of the time, it's caused by a loaded PHP extension that is broken.
* Have you set up the MSSQL database details correctly in `.env` file?
* Have you made IIS expose errors? (see "How do I make IIS expose errors..." below)
* Are you running non-standard PHP extensions? If so, try unloading them one by one
* Make sure you're using the latest [[http://www.microsoft.com/downloads/en/details.aspx?FamilyID=80E44913-24B4-4113-8807-CAAE6CF2CA05&displaylang=en/|Microsoft Drivers for PHP for SQL Server]]
**Q: I get the error "HTTP Error 500.0 - Internal Server Error - C:\Program Files (x86)\PHP\php-cgi.exe - The FastCGI process exceeded configured request timeout"**
**A:** A script has been running for a long time, such as a unit test. To fix this, you'll need to increase the request timeout to a higher value in both IIS and PHP. Refer to the IIS FastCGI configuration documentation and PHP configuration parts of this document for where to change the appropriate values.
**Q: I cannot access SQL Server from a remote server, such as a development environment**
**A:** This is because the firewall settings on the server hosting SQL Server 2008 are too strict - you need to tweak the firewall to accept incoming connections.
Do the following to open a firewall port:
* In Control Panel, open Windows Firewall
* Click Allow a program through Windows Firewall
* Click the Exceptions tab, and then click Add Port
* In the Add a Port dialog box, in the Name field, enter SQL Server
* In the Port number box, type the port number of the instance of the Database Engine, such as 1433 for the default instance
* Verify that **TCP** is selected, and then click OK
To open the port to expose the SQL Server Browser service, click Add Port, type SQL Server Browser in the Name text box, type **1434** in the Port Number text box, select **UDP**, and then click OK
And then verify TCP/IP access is enabled:
* Open SQL Server Configuration Manager
* In the node "Protocols for MSSQLSERVER" (or for your instance name) verify TCP/IP is **Enabled**
* Restart SQL Server if protocol changes were made
**Q: When I try running the unit tests, I get this error: "Uncaught Zend_Cache_Exception: cache_dir is not writable"**
**A:** Sometimes you can't access the TEMP folder because the current user doesn't have permission.
The solution is to create a **silverstripe-cache** directory in your project directory. For example, inside **C:\inetpub\wwwroot\silverstripe**. Do the following:
* Create a **silverstripe-cache** directory in the directory where you installed SilverStripe
* Right click the newly created directory, and select the Security tab
* Click the Edit button
* Click the Users item in the list, and then click the Modify checkbox
* Click Apply - accept the warning that is given
* Click OK
NOTE: When **fastcgi.impersonate = 1** is set in php.ini, the current user logged in on the domain will be the user the web server runs PHP scripts under e.g "sharvey" if Windows Authentication is enabled. If nobody is logged in, and someone accesses the site anonymously, the web server will run under the "IUSR" credentials.
To find out who the current user is, try echoing the result of get_current_user() inside a test php script.
**Q: When I try to access my SilverStripe site for the first time, I get a 404 error**
**A:** Try accessing dev/build?username=admin&password=password at the end of the URL you requested. For example, `http://localhost/ss/dev/build?username=admin&password=password`. This will ensure the database is built properly
**Q: How do I make IIS expose errors instead of giving a generic 500 or 404 page?**
**A:** In IIS manager, double click Error Pages for the top level server node on the left. You'll be presented with a list of status codes, and a path to the error page. To show detailed errors remotely AND locally, click Edit Feature Settings on the right panel under Actions. From the dialog box that pops up, select Detailed errors. Restart IIS for the changes to take effect. This also means that from now on, the custom error pages SilverStripe generate will be used instead of the default IIS one.
Also, make sure that display_errors, display_startup_errors and html_errors in are set to On in php.ini.
**Q: I get a 500 server error when trying to access the SilverStripe site. e.g. `http://localhost/ss`**
**A:** One of the reasons why this could be happening is the web.config file inside the ss directory has XML that is not well formed. Make sure there are NO spaces before the starting <?xml> tag, and make sure that everything is tabbed out correctly.
One other thing you can do is make sure Show friendly HTTP error messages is unchecked in Internet Explorer. You can find this in Tools > Internet Options > Advanced.
Make sure errors are exposed by following the troubleshooting question above "How do I make IIS expose errors..."
If this still doesn't help, enable Failed Request Tracing in IIS. You could also try using DebugView, a useful debugging tool for Windows.
**Q: I get an error about SQL Server Driver for PHP requiring "SQL Server 2008 Native Client ODBC Driver (SP1 or later)"**
**A:** If you're accessing a SQL Server database that's on another server, you need to install SQL Server 2008 Native Client on the client web server that accesses the external database server.
**Q: When I try to load the CMS, the SilverStripe logo stays there and the CMS doesn't load.**
**A:** Make sure the assets directory exists, and is writable by the web server. This happens on test/live mode because SilverStripe will try to combine the javascript files, and put them in the assets directory. If it's not writable, or doesn't exist, then the CMS will fail to load.
**Q: Performance of SilverStripe is slow on Windows.**
**A:** A non-thread safe of PHP is recommended for use with IIS. Thread safety checks are not required, and you'll get a performance boost by not using a thread safe version. If possible, use a version compiled in VC9 instead of VC6. VC9 versions require you to have the [Microsoft 2008 C++ Runtime (x86)](http://www.microsoft.com/downloads/details.aspx?FamilyID=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF) or the [Microsoft 2008 C++ Runtime (x64)](http://www.microsoft.com/downloads/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6&displaylang=en) installed
You should also ensure you are using the latest version of the [Microsoft Drivers for PHP for SQL Server](http://www.microsoft.com/downloads/en/details.aspx?FamilyID=80E44913-24B4-4113-8807-CAAE6CF2CA05&displaylang=en) driver.
Try increasing the IIS **MaxInstances** in IIS Manager > FastCGI from 4 to a higher value. For quad core CPUs, a higher value such as **32** should prove to provide a performance enhancement.
You can also [install wincache](http://learn.iis.net/page.aspx/678/use-the-windows-cache-extension-for-php/), to improve performance on live sites.
You can also try installing and enabling static content compression for IIS on live sites. Do this in IIS Manager > Compression.
Doing all of the above should provide a significant performance boost to your site.
**Q: I can upload files, but I get server error when downloading them.**
**Q: I get a lot of stale session files - garbage collector seems not running.**
**A:** This is because of the permissions being incorrectly configured on the temporary upload or session storage folders that the PHP uses. See *Folder permissions for PHP* section for how to configure this correctly.

100
docs/en/00_Getting_Started/01_Installation/How_To/Configure_Nginx.md
View File

@ -1,100 +0,0 @@
# Nginx
These instructions are also covered on the
[Nginx Wiki](https://www.nginx.com/resources/wiki/start/topics/recipes/silverstripe/).
The prerequisite is that you have already installed Nginx and you are
able to run PHP files via the FastCGI-wrapper from Nginx.
Now you need to set up a virtual host in Nginx with configuration settings
that are similar to those shown below.
<div class="notice" markdown='1'>
If you don't fully understand the configuration presented here, consult the
[nginx documentation](http://nginx.org/en/docs/).
Especially be aware of [accidental php-execution](https://nealpoole.com/blog/2011/04/setting-up-php-fastcgi-and-nginx-dont-trust-the-tutorials-check-your-configuration/ "Don't trust the tutorials") when extending the configuration.
</div>
## Caveats about the sample configuration below
* It does not cover serving securely over HTTPS.
* It uses the new filesystem layout (with `public` directory) introduced in version 4.1.0. If your installation has been upgraded to 4.1+ from an older version and you have not [upgraded to the public folder](/changelogs/4.1.0.md), see the version of this documentation for version 4.0.
* The regular expression for allowed file types must be manually updated if the File.allowed_extensions list is updated.
* The error pages for 502 (Bad Gateway) and 503 (Service Unavailable) need to be manually created and published in the CMS (assuming use of the silverstripe/errorpage module).
```nginx
server {
include mime.types;
default_type application/octet-stream;
client_max_body_size 0; # Manage this in php.ini (upload_max_filesize & post_max_size)
listen 80;
root /path/to/ss/folder/public;
server_name example.com www.example.com;
# Defend against SS-2015-013 -- http://www.silverstripe.org/software/download/security-releases/ss-2015-013
if ($http_x_forwarded_host) {
return 400;
}
location / {
try_files $uri /index.php?$query_string;
}
error_page 404 /assets/error-404.html;
error_page 500 /assets/error-500.html;
# See caveats
error_page 502 /assets/error-500.html;
error_page 503 /assets/error-500.html;
# Support assets & resources #
# Never serve .gitignore, .htaccess, or .method
location ~ /\.(gitignore|htaccess|method)$ {
return 403;
}
# Protect the .protected folder
location ~ ^/assets/.protected/ {
return 403;
}
# Handle allowed file types (see caveats)
# Pass unfound files to SilverStripe to check draft images
location ~ ^/assets/.*\.(?i:css|js|ace|arc|arj|asf|au|avi|bmp|bz2|cab|cda|csv|dmg|doc|docx|dotx|flv|gif|gpx|gz|hqx|ico|jpeg|jpg|kml|m4a|m4v|mid|midi|mkv|mov|mp3|mp4|mpa|mpeg|mpg|ogg|ogv|pages|pcx|pdf|png|pps|ppt|pptx|potx|ra|ram|rm|rtf|sit|sitx|tar|tgz|tif|tiff|txt|wav|webm|wma|wmv|xls|xlsx|xltx|zip|zipx)$ {
sendfile on;
try_files $uri /index.php?$query_string;
}
# Allow the error pages. Fail with 404 Not found.
location ~ ^/assets/error-\d\d\d\.html$ {
try_files $uri =404;
}
# Fail all other assets requests as 404 Not found
# Could also use 403 Forbidden or 444 (nginx drops the connection)
location ~ ^/assets/ {
return 404;
}
# End of assets & resources support #
location /index.php {
fastcgi_buffer_size 32k;
fastcgi_busy_buffers_size 64k;
fastcgi_buffers 4 32k;
fastcgi_keep_conn on;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
```
The above configuration sets up a virtual host `example.com` with
rewrite rules suited for SilverStripe. The location block for index.php
passes the php script to the FastCGI-wrapper via a TCP socket.
Now you can proceed with the SilverStripe installation normally.

169
docs/en/00_Getting_Started/01_Installation/How_To/MySQL_SSL_Support.md
View File

@ -1,169 +0,0 @@
title: MySQL SSL Support
summary: Setting up MySQL SSL certificates to work with Silverstripe
# MySQL SSL Support: Why do I need it?
In a typical Silverstripe set up, you will only need to use a single host to function as the web server, email server, database server, among others.
In some cases, however, you may be required to connect to a database on a remote host. Connecting to a remote host without SSL encryption exposes your data to [packet sniffing](http://www.linuxjournal.com/content/packet-sniffing-basics) and may compromise the security of your Silverstripe instance.
This article demonstrates how to generate SSL certificates using MySQL and implementing them in Silverstripe.
<div class="notice" markdown='1'>
This article assumes that you have `MySQL` and `OpenSSL` installed.
</div>
## Generating Certificates
There are three components to an SSL certificate implementation. The first two components are the ***private key***, and the ***public certificate***, which are mathematically-generated, symetrical pieces of the puzzle that allow [public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) to work. The third component is the [Certificate Authority (CA) certificate](https://en.wikipedia.org/wiki/Certificate_authority) that signs the pubic key to prove its validity.
In the case of MySQL, we will need to generate three sets of certificates, namely:
- the CA key and certificate
- the server key and certificate
- the client key and certificate
We also need to sign the certificates with our generated CA.
The commands below illustrate how to do so on your MySQL host.
<div class="notice" markdown='1'>
The following commands will work on Linux/Unix based servers. For other servers such as windows, refer to the [MySQL documentation](https://dev.mysql.com/doc/refman/5.7/en/creating-ssl-files-using-openssl.html)
</div>
:::bash
# Create directory
sudo mkdir ssl
cd ssl
# Generate CA key and CA cert
sudo openssl genrsa 2048 | sudo tee -a ca-key.pem
sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.pem
# Generate SERVER key and server certificate signing request
# IMPORTANT: the common name of the certificate should match the domain name of your host!
sudo openssl rsa -in server-key.pem -out server-key.pem
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.pem -out server-req.pem
# Generate and sign SERVER certificate
sudo openssl x509 -req -in server-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
# Generate CLIENT key and certificate signing request
sudo openssl rsa -in client-key.pem -out client-key.pem
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.pem -out client-req.pem
# Generate and sign CLIENT certificate
sudo openssl x509 -req -in client-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem
# Verify validity of generated certificates
sudo openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem
<div class="warning" markdown='1'>
After generating the certificates, make sure to set the correct permissions to prevent unauthorized access to your keys!
It is critical that the key files (files ending in *key.pem) are kept secret. Once these files are exposed, you will need to regenerate the certificates to prevent exposing your data traffic.
</div>
:::bash
# Set permissions readonly permissions and change owner to root
sudo chown root:root *.pem
sudo chmod 440 *.pem
# Server certificates need to be readable by mysql
sudo chgrp mysql server*.pem
sudo mv *.pem /etc/mysql/ssl
## Setting up MySQL to use SSL certificates
<div class="notice" markdown='1'>
For Debian/Ubuntu instances, the configuration file is usually in `/etc/mysql/my.cnf`. Refer to your MySQL manual for more information
</div>
We must edit the MySQL configuration to use the newly generated certificates.
Edit your MySQL configuration file as follows.
[mysqld]
...
ssl-ca=/etc/mysql/ca-cert.pem
ssl-cert=/etc/mysql/server-cert.pem
ssl-key=/etc/mysql/server-key.pem
# IMPORTANT! When enabling MySQL remote connections, make sure to take adequate steps to secure your machine from unathorized access!
bind-address=0.0.0.0
<div class="warning" markdown='1'>
Enabling remote connections to your MySQL instance introduces various security risks. Make sure to take appropriate steps to secure your instance by using a strong password, disabling MySQL root access, and using a firewall to only accept qualified hosts, for example.
</div>
Make sure to restart your MySQL instance to reflect the changes.
:::bash
sudo service mysql restart
## Setting up Silverstripe to connect to MySQL
Now that we have successfully setup the SSL your MySQL host, we now need to configure Silverstripe to use the certificates.
### Copying SSL Certificates
First we need to copy the client certificate files to the Silverstripe instance. You will need to copy:
- `client-key.pem`
- `client-cert.pem`
- `ca-cert.pem`
<div class="warning" markdown='1'>
Make sure to only copy `client-key.pem`, `client-cert.pem`, and `ca-cert.pem` to avoid leaking your credentials!
</div>
On your Silverstripe instance:
:::bash
# Secure copy over SSH via rsync command. You may use an alternative method if desired.
rsync -avP user@db1.example.com:/path/to/client/certs /path/to/secure/folder
# Depending on your web server configuration, allow web server to read to SSL files
sudo chown -R www-data:www-data /path/to/secure/folder
sudo chmod 750 /path/to/secure/folder
sudo chmod 400 /path/to/secure/folder/*
### Setting up _ss_environment.php to use SSL certificates
<div class="notice" markdown='1'>
`SS_DATABASE_SERVER does not accept IP-based hostnames. Also, if the domain name of the host does not match the common name you used to generate the server certificate, you will get an `SSL certificate mismatch error`.
</div>
Add or edit your `_ss_environment.php` configuration file. (See [Environment Management](/getting_started/environment_management) for more information.)
:::php
<?php
// These four define set the database connection details.
define('SS_DATABASE_CLASS', 'MySQLDatabase');
define('SS_DATABASE_SERVER', 'db1.example.com');
define('SS_DATABASE_USERNAME', 'dbuser');
define('SS_DATABASE_PASSWORD', '<password>');
// These define the paths to the SSL key, certificate, and CA certificate bundle.
define('SS_DATABASE_SSL_KEY', '/home/newdrafts/mysqlssltest/client-key.pem');
define('SS_DATABASE_SSL_CERT', '/home/newdrafts/mysqlssltest/client-cert.pem');
define('SS_DATABASE_SSL_CA', '/home/newdrafts/mysqlssltest/ca- cert.pem');
// When using SSL connections, you also need to supply a username and password to override the default settings
define('SS_DEFAULT_ADMIN_USERNAME', 'username');
define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
When running the installer, make sure to check on the `Use _ss_environment file for configuration` option under the `Database Configuration` section to use the environment file.
## Conclusion
That's it! We hope that this article was able to help you configure your remote MySQL SSL secure database connection.

87
docs/en/00_Getting_Started/01_Installation/How_To/Setup_Nginx_and_HHVM.md
View File

@ -1,87 +0,0 @@
title: Nginx and HHVM
summary: Setting up Nginx and HHVM on Debian/Ubuntu using packages.
# Nginx and HHVM
[HHVM](http://hhvm.com/) is a faster alternative to PHP, in that it runs in a virtual machine
and uses just-in-time (JIT) compilation to achieve better performance over standard PHP.
Installation on Debian or Ubuntu is relatively straightforward, in that HHVM already provide
packages available to use.
Install apt sources on Debian 7 (wheezy):
wget -O - http://dl.hhvm.com/conf/hhvm.gpg.key | sudo apt-key add -
echo deb http://dl.hhvm.com/debian wheezy main | sudo tee /etc/apt/sources.list.d/hhvm.list
Install apt sources on Ubuntu 14.04 (trusty):
wget -O - http://dl.hhvm.com/conf/hhvm.gpg.key | sudo apt-key add -
echo deb http://dl.hhvm.com/ubuntu trusty main | sudo tee /etc/apt/sources.list.d/hhvm.list
Now install the required packages:
sudo apt-get update
sudo apt-get install hhvm libgmp-dev libmemcached-dev
Start HHVM automatically on boot:
sudo update-rc.d hhvm defaults
Please see [Prebuilt Packages for HHVM on HHVM wiki](https://github.com/facebook/hhvm/wiki/Prebuilt%20Packages%20for%20HHVM) for more
installation options.
Assuming you already have nginx installed, you can then run a script to enable support for
nginx and/or apache2 depending on whether they are installed or not:
sudo /usr/share/hhvm/install_fastcgi.sh
For nginx, this will place a file at `/etc/nginx/hhvm.conf` which you can use to include in
your nginx server definitions to provide support for PHP requests.
In order to get SilverStripe working, you need to add some custom nginx configuration.
Create `/etc/nginx/silverstripe.conf` and add this configuration:
fastcgi_buffer_size 32k;
fastcgi_busy_buffers_size 64k;
fastcgi_buffers 4 32k;
location / {
try_files $uri /index.php?$query_string;
}
error_page 404 /assets/error-404.html;
error_page 500 /assets/error-500.html;
location ^~ /assets/ {
try_files $uri =404;
}
location ~ /\.. {
deny all;
}
location ~ web\.config$ {
deny all;
}
The above script passes all non-static file requests to `/index.php` in the webroot which relies on
`hhvm.conf` being included prior so that php requests are handled.
Now in your nginx `server` configuration you can then include the `hhvm.conf` and `silverstripe.conf` files
to complete the configuration required for PHP/HHVM and SilverStripe.
e.g. `/etc/nginx/sites-enabled/mysite`:
server {
listen 80;
root /var/www/mysite/public;
server_name www.example.com;
error_log /var/log/nginx/mysite.error.log;
access_log /var/log/nginx/mysite.access.log;
include /etc/nginx/hhvm.conf;
include /etc/nginx/silverstripe.conf;
}
For more information on nginx configuration, please see the [nginx installation](configure_nginx) page.

27
docs/en/00_Getting_Started/01_Installation/index.md
View File

@ -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)

0
docs/en/00_Getting_Started/01_Installation/05_Common_Problems.md → docs/en/00_Getting_Started/05_Common_Problems.md
View File

90
docs/en/00_Getting_Started/index.md
View File

@ -1,77 +1,53 @@
title: Getting Started 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. 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 is most commonly served using Apache and MySQL/MariaDB.
The best way to get SilverStripe is to [install with Composer](composer). Composer is a package management tool for PHP that If you are setting up your own environment,
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. 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're running Apache with MySQL/MariaDB already,
* 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. 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. vendor/bin/sake dev/build
* [Install using nginx and HHVM](installation/how_to/setup_nginx_and_hhvm) - nginx and [HHVM](http://hhvm.com/) as a faster alternative to PHP. ```
### 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 ## 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/). 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)

2
docs/en/01_Lessons/index.md
View File

@ -26,5 +26,5 @@ introduction: The lessons take a step by step look at how to build a SilverStrip
## Help: If you get stuck ## 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. * [SilverStripe Community](http://www.silverstripe.org/community/): Join our community chat via Slack, or ask a question on Stack Overflow.

3
docs/en/02_Developer_Guides/01_Templates/03_Requirements.md
View File

@ -46,7 +46,8 @@ SilverStripe projects should not track the "resources" directory in their source
### Exposing assets in the web root ### 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. 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.

2
docs/en/02_Developer_Guides/14_Files/03_File_Security.md
View 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" 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 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` appropriate file extensions for your instance. This can be done by setting the `File.allowed_extensions`

4
docs/en/04_Changelogs/4.0.0.md
View File

@ -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. 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 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. guide for configuration instruction.
### Image handling {#image-handling} ### 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. configuration customisation is done via overriding these templates.
Depending on your server configuration, it may also be necessary to adjust your assets folder 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. guide for configuration instruction.
If upgrading from an existing installation, make sure to invoke `?flush=all` at least once. If upgrading from an existing installation, make sure to invoke `?flush=all` at least once.