diff --git a/docs/en/00_Getting_Started/03_Environment_Management.md b/docs/en/00_Getting_Started/03_Environment_Management.md index 781631a6f86..eec7369b824 100644 --- a/docs/en/00_Getting_Started/03_Environment_Management.md +++ b/docs/en/00_Getting_Started/03_Environment_Management.md @@ -1,112 +1,59 @@ # Environment management -As website developers, we noticed that we had a few problems. You may have the same problems: - -* On our development laptops, we have a number of sites, but the database connection details are the same for each of -them. Why should we have to go through the installation process and re-enter them each time? -* Each of those sites needed to be in development mode when we were editing them on our laptops, but in production mode -when we deploy them to our servers. Additionally, our production host's database connection details will likely be -different than our local server. - -SilverStripe comes with a solution to this: the `_ss_environment.php` file. You can put a single `_ss_environment.php` -file in your "projects" folder on your development box, and it will be used by each of your development sites. - -## Setting up your development machine with _ss_environment.php - -In this example, we assume that you are managing multiple projects as subfolders of `~/Sites/`, and that you can visit -these at `http://localhost/`. For example, you might have a project at `~/Sites/myproject/`, and visit it at -`http://localhost/myproject/`. - -Create a new file, `~/Sites/_ss_environment.php`. Put the following content in it, editing the values of the -"SS_DATABASE_..." and "SS_DEFAULT_ADMIN_..." defines as appropriate. - - :::php - '); - - // This sets a prefix, which is prepended to the $database variable. This is - // helpful mainly on shared hosts, when every database has a prefix. - define('SS_DATABASE_PREFIX', 'simon_'); - - // These two lines are a bit complicated. If I'm connecting to the server from - // 127.0.0.1 or MyIP and I'm using a browser with a + in the UserAgent, the site - // is put in dev mode, otherwise it is put in live mode. Most sites would only - // need to put the site in either dev or live mode, thus wont need the IP checks - if(isset($_SERVER['REMOTE_ADDR']) && ($_SERVER['REMOTE_ADDR'] == '127.0.0.1' || ($_SERVER['REMOTE_ADDR'] == '' - && strpos($_SERVER['HTTP_USER_AGENT'], '+') !== false))) - define('SS_ENVIRONMENT_TYPE', 'dev'); - else - define('SS_ENVIRONMENT_TYPE', 'live'); - - // These two defines sets a default login which, when used, will always log - // you in as an admin, even creating one if none exist. - define('SS_DEFAULT_ADMIN_USERNAME', ''); - define('SS_DEFAULT_ADMIN_PASSWORD', ''); - - // This causes errors to be written to the BASE_PATH/silverstripe.log file. - // Path must be relative to BASE_PATH - define('SS_ERROR_LOG', 'silverstripe.log'); - - // This is used by sake to know which directory points to which URL - global $_FILE_TO_URL_MAPPING; - $_FILE_TO_URL_MAPPING['/var/www'] = 'http://simon.geek.nz'; - -## Available Constants +As part of website development and hosting it is natural for our sites to be hosted on several different environments. +These can be our laptops for local development, a testing server for customers to test changes on, or a production +server. + +For each of these environments we may require slightly different configurations for our servers. This could be our debug +level, caching backends, or - of course - sensitive information such as database credentials. + +In particular these sensitive credentials should not be stored in a VCS or our project code and should only be stored on +the environment in question. + +To solve this problem of setting variables per environment we use environment variables with the help of the +[PHPDotEnv](https://github.com/vlucas/phpdotenv) library by Vance Lucas. + +## Managing environment variables with `.env` files + +By default the `.env` must be placed in your webroot. If this file exists, it will be automatically loaded by the +framework and the environment variables will be set. An example `.env` file is included in the default installer named +`.env.example`. + +## Managing environment variables with Apache + +You can set "real" environment variables using Apache. Please +[see the Apache docs for more information](https://httpd.apache.org/docs/current/env.html) + +## How to access the environment variables + +Accessing the environment varaibles is easy and can be done using the `getenv` method or in the `$_ENV` and `$_SERVER` +super-globals: + +```php +getenv('SS_DATABASE_CLASS'); +$_ENV['SS_DATABASE_CLASS']; +$_SERVER['SS_DATABASE_CLASS']; +``` + +## Including an extra `.env` file + +Sometimes it may be useful to include an extra `.env` file - on a shared local development environment where all +database credentials could be the same. To do this, you can add this snippet to your `mysite/_config.php` file: + +```php +try { + (new \Dotenv\Dotenv('/path/to/env/'))->load(); +} catch (\Dotenv\Exception\InvalidPathException $e) { + // no file found +} +``` + +## Core environment variables + +SilverStripe core environment variables are listed here, though you're free to define any you need for your application. | Name | Description | | ---- | ----------- | -| `TEMP_FOLDER` | Absolute file path to store temporary files such as cached templates or the class manifest. Needs to be writeable by the webserver user. Defaults to *silverstripe-cache* in the webroot, and falls back to *sys_get_temp_dir()*. See *getTempFolder()* in *framework/core/TempPath.php*.| | `SS_DATABASE_CLASS` | The database class to use, MySQLPDODatabase, MySQLDatabase, MSSQLDatabase, etc. defaults to MySQLDatabase.| | `SS_DATABASE_SERVER`| The database server to use, defaulting to localhost.| | `SS_DATABASE_USERNAME`| The database username (mandatory).| @@ -125,3 +72,11 @@ This is my `_ss_environment.php` file. I have it placed in `/var`, as each of th | `SS_SEND_ALL_EMAILS_TO`| If you define this constant, all emails will be redirected to this address.| | `SS_SEND_ALL_EMAILS_FROM`| If you define this constant, all emails will be sent from this address.| | `SS_ERROR_LOG` | Relative path to the log file. | +| `SS_PROTECTED_ASSETS_PATH` | Path to secured assets - defaults to ASSET_PATH/.protected | +| `SS_DATABASE_MEMORY` | Used for SQLite3 DBs | +| `SS_TRUSTED_PROXY_PROTOCOL_HEADER` | Used to define the proxy header to be used to determine HTTPS status | +| `SS_TRUSTED_PROXY_IP_HEADER` | Used to define the proxy header to be used to determine request IPs | +| `SS_TRUSTED_PROXY_HOST_HEADER` | Used to define the proxy header to be used to determine the requested host name | +| `SS_TRUSTED_PROXY_IPS` | IP address or CIDR range to trust proxy headers from | +| `SS_ALLOWED_HOSTS` | A comma deliminated list of hostnames the site is allowed to respond to | +| `SS_MANIFESTCACHE` | The manifest cache to use (defaults to file based caching) |