diff --git a/docs/en/00_Getting_Started/01_Installation/03_Windows.md b/docs/en/00_Getting_Started/01_Installation/03_Windows.md
index ed9bf0b45..739e441e2 100644
--- a/docs/en/00_Getting_Started/01_Installation/03_Windows.md
+++ b/docs/en/00_Getting_Started/01_Installation/03_Windows.md
@@ -38,7 +38,7 @@ $ composer create-project silverstripe/installer ./silverstripe
 * 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 _ss_environment.php either in the webroot or a directory above webroot and setup as per the [Environment Management process](/getting_started/environment_management).
+* 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` - 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.
diff --git a/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md b/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md
index 1fa32603e..40ba16355 100644
--- a/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md
+++ b/docs/en/00_Getting_Started/01_Installation/04_Other_installation_Options/Windows_IIS7.md
@@ -160,22 +160,21 @@ You will need to give **Modify** permission to **IUSR** user. To do it right cli
 
 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 **_ss_environment.php** in **C:\inetpub\wwwroot**
+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 _ss_environment.php file, insert the following code:
+Inside the newly created `.env` file, insert the following code:
 
-	<?php
-	/* What kind of environment is this: development, test, or live (ie, production)? */
-	define('SS_ENVIRONMENT_TYPE', 'dev');
-	/* Database connection */
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'sa');
-	define('SS_DATABASE_PASSWORD', '');
-	/* Configure a default username and password to access the CMS on all sites in this environment */
-	define('SS_DEFAULT_ADMIN_USERNAME', 'username');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+	# 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.
 
@@ -211,7 +210,7 @@ If all goes to plan, you're done, and you should see a basic template with a few
 
 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 _ss_environment.php?
+  * 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]]
diff --git a/docs/en/00_Getting_Started/02_Composer.md b/docs/en/00_Getting_Started/02_Composer.md
index b93aa975a..e1ebaa0f6 100644
--- a/docs/en/00_Getting_Started/02_Composer.md
+++ b/docs/en/00_Getting_Started/02_Composer.md
@@ -129,20 +129,18 @@ Since SilverStripe modules are installed into their own folder, you have to mana
 
 Here is the default SilverStripe [.gitignore](http://git-scm.com/docs/gitignore) with the forum module ignored
 
-```
-assets/*
-_ss_environment.php
-tools/phing-metadata
-silverstripe-cache
-.buildpath
-.project
-.settings
-.idea
-.DS_Store
-vendor/
-# Don't include the forum module, as this will be installed with composer
-forum
-```
+	```assets/*
+	.env
+	tools/phing-metadata
+	silverstripe-cache
+	.buildpath
+	.project
+	.settings
+	.idea
+	.DS_Store
+	vendor/
+	# Don't include the forum module, as this will be installed with composer
+	forum```
 
 In large projects it can get difficult to manage your [.gitignore](http://git-scm.com/docs/gitignore) and ensure it contains all composer managed modules and themes.
 
diff --git a/docs/en/00_Getting_Started/03_Environment_Management.md b/docs/en/00_Getting_Started/03_Environment_Management.md
index 781631a6f..9a817a293 100644
--- a/docs/en/00_Getting_Started/03_Environment_Management.md
+++ b/docs/en/00_Getting_Started/03_Environment_Management.md
@@ -1,112 +1,65 @@
 # Environment management
 
-As website developers, we noticed that we had a few problems.  You may have the same problems:
+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.
 
-*  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.
+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.
 
-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.
+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.
 
-## Setting up your development machine with _ss_environment.php
+## Security considerations
 
-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/`.
+Sensitive credentials should not be stored in a VCS or project code and should only be stored on the environment in 
+question. When using live environments the use of `.env` files is discouraged and instead one should use "first class"
+environment variables.
 
-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.
+If you do use a `.env` file on your servers, you must ensure that external access to `.env` files is blocked by the
+webserver.
 
-	:::php
-	<?php
-	/* What kind of environment is this: development, test, or live (ie, production)? */
-	define('SS_ENVIRONMENT_TYPE', 'dev/test/live');
-	
-	/* Database connection */
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'root');
-	define('SS_DATABASE_PASSWORD', '');
-	
-	/* Configure a default username and password to access the CMS on all sites in this environment. */
-	define('SS_DEFAULT_ADMIN_USERNAME', 'username');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+## Managing environment variables with `.env` files
 
+By default the `.env` must be placed in your project root (ie: same folder as you `composer.json`) or the parent
+directory. 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`.
 
-Now, edit each of your site's configuration file, usually `mysite/_config.php`.  Delete all mention
-of `$databaseConfig` and `Director::set_dev_servers`, and instead make sure that you file starts like this.
+## Managing environment variables with Apache
 
-	:::php
-	<?php
-	
-	global $project;
-	$project = 'mysite';
-	
-	global $database;
-	$database = '(databasename)';
-	
-	// Use _ss_environment.php file for configuration
-	require_once("conf/ConfigureFromEnv.php");
+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
 
-## How it works
+Accessing the environment varaibles is easy and can be done using the `getenv` method or in the `$_ENV` and `$_SERVER`
+super-globals:
 
-The mechanism by which the `_ss_environment.php` files work is quite simple.  Here's how it works:
+```php
+getenv('SS_DATABASE_CLASS');
+$_ENV['SS_DATABASE_CLASS'];
+$_SERVER['SS_DATABASE_CLASS'];
+```
 
-*  At the beginning of SilverStripe's execution, the `_ss_environment.php` file is searched for, and if it is found, it's
-included.  SilverStripe looks in all the parent folders of framework up to the server root (using the REAL location of
-the dir - see PHP realpath()):
-*  The `_ss_environment.php` file sets a number of "define()".
-*  "conf/ConfigureFromEnv.php" is included from within your `mysite/_config.php`.  This file has a number of regular
-configuration commands that use those defines as their arguments.  If you are curious, open up
-`framework/conf/ConfigureFromEnv.php` and see for yourself!
+## Including an extra `.env` file
 
-### An Example
+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:
 
-This is my `_ss_environment.php` file. I have it placed in `/var`, as each of the sites are in a subfolder of `/var`.
+```php
+try {
+	(new \Dotenv\Dotenv('/path/to/env/'))->load();
+} catch (\Dotenv\Exception\InvalidPathException $e) {
+	// no file found
+}
+```
 
-	:::php
-	<?php
-	// These four define set the database connection details.
-	define('SS_DATABASE_CLASS', 'MySQLPDODatabase');
-	define('SS_DATABASE_SERVER', 'localhost');
-	define('SS_DATABASE_USERNAME', 'root');
-	define('SS_DATABASE_PASSWORD', '<password>');
-	
-	// 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'] == '<MyIP>' 
-	&& 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', '<email>');
-	define('SS_DEFAULT_ADMIN_PASSWORD', '<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';
+## Core environment variables
 
-## Available Constants
+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 +78,12 @@ 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) |
+| `SS_IGNORE_DOT_ENV` | If set the .env file will be ignored. This is good for live to mitigate any performance implications of loading the .env file |
diff --git a/docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md b/docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md
index 99c8ca188..3bf84b7cd 100644
--- a/docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md
+++ b/docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md
@@ -4,11 +4,10 @@ summary: Site configuration variables such as database connection details, envir
 # Environment Variables
 
 Environment specific variables like database connection details, API keys and other server configuration should be kept 
-outside the application code in a separate `_ss_environment.php` file. This file is stored outside the web root and 
-version control for security reasons. 
+outside the application code in a separate `.env` file. This file is stored in the web root and 
+kept out of version control for security reasons.
 
-For more information on the environment file, see the [Environment Management](../../getting_started/environment_management/) 
-documentation.
+For more information see our docs on [Environment Management](../../getting_started/environment_management/).
 
 Data which isn't sensitive that can be in version control but is mostly static such as constants is best suited to be 
-included through the [Configuration API](configuration) based on the standard environment types (dev / test / live).
\ No newline at end of file
+included through the [Configuration API](configuration) based on the standard environment types (dev / test / live).
diff --git a/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md b/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md
index 65d5b42f9..fd72a44d6 100644
--- a/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md
+++ b/docs/en/02_Developer_Guides/07_Debugging/00_Environment_Types.md
@@ -13,10 +13,9 @@ The definition of setting an environment type in a `mysite/_config/app.yml` look
 	SilverStripe\Control\Director:
 	  environment_type: 'dev'
 
-The definition of setting an environment type in a `_ss_environment.php` file looks like
+The definition of setting an environment type in a `.env` file looks like
 
-	:::php
-	define('SS_ENVIRONMENT_TYPE', 'dev');
+	SS_ENVIRONMENT_TYPE="dev"
 
 The three environment types you can set are `dev`, `test` and `live`.
 
diff --git a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
index 8e4d8f7f3..dc2598661 100644
--- a/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
+++ b/docs/en/02_Developer_Guides/09_Security/03_Authentication.md
@@ -37,13 +37,12 @@ When a new SilverStripe site is created for the first time, it may be necessary
 CMS access for the first time. SilverStripe provides a default admin configuration system, which allows a username
 and password to be configured for a single special user outside of the normal membership system.
 
-It is advisable to configure this user in your `_ss_environment.php` file outside of the web root, as below:
+It is advisable to configure this user in your `.env` file inside of the web root, as below:
 
-	:::php
-	// Configure a default username and password to access the CMS on all sites in this environment.
-	define('SS_DEFAULT_ADMIN_USERNAME', 'admin');
-	define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+	# Configure a default username and password to access the CMS on all sites in this environment.
+	SS_DEFAULT_ADMIN_USERNAME="admin"
+	SS_DEFAULT_ADMIN_PASSWORD="password"
 
 When a user logs in with these credentials, then a [api:Member] with the Email 'admin' will be generated in
 the database, but without any password information. This means that the password can be reset or changed by simply
-updating the `_ss_environment.php` file.
+updating the `.env` file.
diff --git a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md b/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md
index cd416a127..9dc949973 100644
--- a/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md
+++ b/docs/en/02_Developer_Guides/09_Security/04_Secure_Coding.md
@@ -537,11 +537,10 @@ as well as the login form.
 
 To prevent a forged hostname appearing being used by the application, SilverStripe
 allows the configure of a whitelist of hosts that are allowed to access the system. By defining
-this whitelist in your _ss_environment.php file, any request presenting a `Host` header that is
+this whitelist in your `.env` file, any request presenting a `Host` header that is
 _not_ in this list will be blocked with a HTTP 400 error:
 
-	:::php
-	define('SS_ALLOWED_HOSTS', 'www.mysite.com,mysite.com,subdomain.mysite.com');
+	SS_ALLOWED_HOSTS="www.mysite.com,mysite.com,subdomain.mysite.com"
 
 Please note that if this configuration is defined, you _must_ include _all_ subdomains (eg www.)
 that will be accessing the site.
@@ -556,14 +555,12 @@ mechanisms, as rewritten urls could persist between requests in order to misdire
 into visiting external sites.
 
 In order to prevent this kind of attack, it's necessary to whitelist trusted proxy
-server IPs using the SS_TRUSTED_PROXY_IPS define in your _ss_environment.php.
+server IPs using the SS_TRUSTED_PROXY_IPS define in your `.env`.
 
-
-	:::php
-	define('SS_TRUSTED_PROXY_IPS', '127.0.0.1,192.168.0.1');
-	define('SS_TRUSTED_PROXY_HOST_HEADER', 'HTTP_X_FORWARDED_HOST');
-	define('SS_TRUSTED_PROXY_IP_HEADER', 'HTTP_X_FORWARDED_FOR');
-	define('SS_TRUSTED_PROXY_PROTOCOL_HEADER', 'HTTP_X_FORWARDED_PROTOCOL');
+	SS_TRUSTED_PROXY_IPS="127.0.0.1,192.168.0.1"
+	SS_TRUSTED_PROXY_HOST_HEADER="HTTP_X_FORWARDED_HOST"
+	SS_TRUSTED_PROXY_IP_HEADER="HTTP_X_FORWARDED_FOR"
+	SS_TRUSTED_PROXY_PROTOCOL_HEADER="HTTP_X_FORWARDED_PROTOCOL"
 
 At the same time, you'll also need to define which headers you trust from these proxy IPs. Since there are multiple ways through which proxies can pass through HTTP information on the original hostname, IP and protocol, these values need to be adjusted for your specific proxy. The header names match their equivalent `$_SERVER` values.
 
@@ -571,14 +568,14 @@ If there is no proxy server, 'none' can be used to distrust all clients.
 If only trusted servers will make requests then you can use '*' to trust all clients.
 Otherwise a comma separated list of individual IP addresses should be declared.
 
-This behaviour is enabled whenever SS_TRUSTED_PROXY_IPS is defined, or if the
+This behaviour is enabled whenever `SS_TRUSTED_PROXY_IPS` is defined, or if the
 `BlockUntrustedIPs` environment variable is declared. It is advisable to include the
 following in your .htaccess to ensure this behaviour is activated.
 
 
 	<IfModule mod_env.c>
 		# Ensure that X-Forwarded-Host is only allowed to determine the request
-		# hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your _ss_environment.php
+		# hostname for servers ips defined by SS_TRUSTED_PROXY_IPS in your .env
 		# Note that in a future release this setting will be always on.
 		SetEnv BlockUntrustedIPs true
 	</IfModule>
@@ -586,7 +583,7 @@ following in your .htaccess to ensure this behaviour is activated.
 
 In a future release this behaviour will be changed to be on by default, and this environment
 variable will be no longer necessary, thus it will be necessary to always set
-SS_TRUSTED_PROXY_IPS if using a proxy.
+`SS_TRUSTED_PROXY_IPS` if using a proxy.
 
 ##  Related
 
diff --git a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md b/docs/en/02_Developer_Guides/14_Files/03_File_Security.md
index 8f92cf7f9..19d6d4579 100644
--- a/docs/en/02_Developer_Guides/14_Files/03_File_Security.md
+++ b/docs/en/02_Developer_Guides/14_Files/03_File_Security.md
@@ -232,11 +232,10 @@ In order to better ensure these files are protected, it's recommended to move th
 root altogether.
 
 For instance, given your web root is in the folder `/sites/mysite/www`, you can tell the asset store
-to put protected files into `/sites/mysite/protected` with the below `_ss_environment.php` setting:
+to put protected files into `/sites/mysite/protected` with the below `.env` setting:
 
 
-    :::php
-    define('SS_PROTECTED_ASSETS_PATH', '/sites/mysite/protected');
+    SS_PROTECTED_ASSETS_PATH="/sites/mysite/protected"
 
 
 ### Configuring: File types
diff --git a/docs/en/02_Developer_Guides/16_Execution_Pipeline/02_Manifests.md b/docs/en/02_Developer_Guides/16_Execution_Pipeline/02_Manifests.md
index eb9812b33..c1c430da3 100644
--- a/docs/en/02_Developer_Guides/16_Execution_Pipeline/02_Manifests.md
+++ b/docs/en/02_Developer_Guides/16_Execution_Pipeline/02_Manifests.md
@@ -15,7 +15,7 @@ By default, manifests are stored on the local filesystem through PHP's `serializ
 Combined with PHP opcode caching this provides fast access.
 In order to share manifests between servers, or centralise cache management,
 other storage adapters are available. These can be configured by a `SS_MANIFESTCACHE` constant,
-placed in your `_ss_environment.php`.
+placed in your `.env`.
 
  * `ManifestCache_File`: The default adapter using PHP's `serialize()`
  * `ManifestCache_File_PHP`: Using `var_export()`, which is faster when a PHP opcode cache is installed
diff --git a/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md b/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md
index 91fc2c77c..7e91aa99b 100644
--- a/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md
+++ b/docs/en/02_Developer_Guides/16_Execution_Pipeline/index.md
@@ -80,13 +80,12 @@ can leave sensitive files exposed to public access (the `RewriteRule` conditions
 
 All requests go through `framework/main.php`, which sets up the execution environment:
 
- * Tries to locate an `_ss_environment.php` 
-   [configuration file](/getting_started/environment_management) in the webroot, 
-   or the two levels above it (to allow sharing configuration between multiple webroots).
+ * Tries to locate an `.env` 
+   [configuration file](/getting_started/environment_management) in the webroot.
  * Sets constants based on the filesystem structure (e.g. `BASE_URL`, `BASE_PATH` and `TEMP_FOLDER`)
  * Normalizes the `url` parameter in preparation for handing it off to `Director`
  * Connects to a database, based on information stored in the global `$databaseConfig` variable.
-   The configuration is either defined in your `_config.php`, or through `_ss_environment.php`
+   The configuration is either defined in your `_config.php`, or through `.env`
  * Sets up [error handlers](../debugging/error_handling)
  * Optionally continues a [session](../cookies_and_sessions/sessions) if the request already contains a session identifier
  * Loads manifests for PHP classes, templates, as well as any [YAML configuration](../configuration).
diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index 2e78b427c..8db4ea5fe 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -49,6 +49,7 @@ guide developers in preparing existing 3.x code for compatibility with 4.0
 * Themes are now configured to cascade, where you can specify a list of themes, and have the template engine
   search programatically through a prioritised list when resolving template and CSS file paths.
 * i18n Updated to use symfony/translation over zend Framework 1. Zend_Translate has been removed.
+* _ss_environment.php files have been removed in favour of `.env` and "real" environment variables.
 
 ## <a name="upgrading"></a>Upgrading
 
@@ -1327,7 +1328,7 @@ handle field-level and form-level messages. This has the following properties:
 
 ### <a name="overview-mailer"></a>Email and Mailer
 
-#### <a name="overview-orm-api"></a>Email Additions / Changes
+#### <a name="overview-mailer-api"></a>Email Additions / Changes
 
 * `Mailer` converted to an interface
 * `SwfitMailer` added as new default mailer
@@ -1335,3 +1336,19 @@ handle field-level and form-level messages. This has the following properties:
 * Default template body variable renamed from `$Body` to `$EmailContent`
 * `$email->setTemplate()` renamed to `$email->setHTMLTemplate()`
 * Added `$email->setPlainTemplate` for rendering plain versions of email
+
+
+### <a name="overview-environment-management"></a>Environment management
+
+See [Environment Management docs](https://docs.silverstripe.org/en/4/getting_started/environment_management/) for full
+details.
+
+The removal of the `_ss_environment.php` file means that conditional logic is no longer available in the environment
+varialbe set-up process. This generally encouraged bad practice and should be avoided. If you still require conditional
+logic early in the bootstrap, this is best placed in the `_config.php` files.
+
+#### Environment file changes
+
+* Removed support for _ss_environment.php in favour of .env and first class environment variables
+* Environment variables now can be set in `.env` file placed in webroot or one level above
+* Environment variables will be read from the environment as well
diff --git a/docs/en/05_Contributing/04_Release_Process.md b/docs/en/05_Contributing/04_Release_Process.md
index 5f0d73860..3d3b7ef60 100644
--- a/docs/en/05_Contributing/04_Release_Process.md
+++ b/docs/en/05_Contributing/04_Release_Process.md
@@ -75,7 +75,7 @@ This change could be committed to a minor release like *3.2.0*, and remains depr
 (e.g. *3.3.0*, *3.4.0*), until a new major release (e.g. *4.0.0*), at which point it gets removed from the codebase. 
 
 Deprecation notices are enabled by default on dev environment, but can be
-turned off via either _ss_environment.php or in your _config.php. Deprecation
+turned off via either `.env` or in your _config.php. Deprecation
 notices are always disabled on both live and test.
 
 
@@ -86,11 +86,10 @@ notices are always disabled on both live and test.
     Deprecation::set_enabled(false);
 
 
-`_ss_environment.php`
+`.env`
 
 
-    :::php
-    define('SS_DEPRECATION_ENABLED', false);
+    SS_DEPRECATION_ENABLED="0"
 
 
 ## Security Releases
diff --git a/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md b/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md
index edca6e272..98d87a546 100644
--- a/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md
+++ b/docs/en/05_Contributing/05_Making_A_SilverStripe_Core_Release.md
@@ -36,30 +36,28 @@ As a core contributor it is necessary to have installed the following set of too
 * [AWS CLI tools](https://aws.amazon.com/cli/):
   `pip install awscli`
 * The `tar` and `zip` commands
-* A good _ss_environment.php setup in your localhost webroot.
+* A good `.env` setup in your localhost webroot.
 
-Example `_ss_environment.php`:
+Example `.env`:
 
-    :::php
-    <?php
-    // Environent
-    define('SS_TRUSTED_PROXY_IPS', '*');
-    define('SS_ENVIRONMENT_TYPE', 'dev');
+    # Environent
+    SS_TRUSTED_PROXY_IPS="*"
+    SS_ENVIRONMENT_TYPE="dev"
     
-    // DB Credentials
-    define('SS_DATABASE_CLASS', 'MySQLDatabase');
-    define('SS_DATABASE_SERVER', '127.0.0.1');
-    define('SS_DATABASE_USERNAME', 'root');
-    define('SS_DATABASE_PASSWORD', '');
+    # DB Credentials
+    SS_DATABASE_CLASS="MySQLDatabase"
+    SS_DATABASE_SERVER="127.0.0.1"
+    SS_DATABASE_USERNAME="root"
+    SS_DATABASE_PASSWORD=""
     
-    // Each release will have its own DB
-    define('SS_DATABASE_CHOOSE_NAME', true);
+    # Each release will have its own DB
+    SS_DATABASE_CHOOSE_NAME=1
     
-    // So you can test releases
-    define('SS_DEFAULT_ADMIN_USERNAME', 'admin');
-    define('SS_DEFAULT_ADMIN_PASSWORD', 'password');
+    # So you can test releases
+    SS_DEFAULT_ADMIN_USERNAME="admin"
+    SS_DEFAULT_ADMIN_PASSWORD="password"
     
-    // Basic CLI hostname
+    # Basic CLI hostname
     global $_FILE_TO_URL_MAPPING;
     $_FILE_TO_URL_MAPPING[__DIR__] = "http://localhost";
 
@@ -198,7 +196,7 @@ and needs to be manually advanced):
   back up to transifex to make them available for translation. Changes to these
   files will also be automatically committed to git.
 * `release:test` Will run all unit tests on this release. Make sure that you
-  setup your `_ss_environment.php` correctly (as above) so that this will work.
+  setup your `.env` correctly (as above) so that this will work.
 * `release:changelog` Will compare the current branch head with `--from` parameter
   version in order to generate a changelog file. This wil be placed into the
   `./framework/docs/en/04_Changelogs/` folder. If an existing file named after