Relocating Drupal 8 Configuration Outside of the Document Root

Drupal configuration is the all-important glue that instructs the Drupal core and contrib code how to operate in the context of the current web application. In Drupal 7, there was no formal configuration API in core. The ctools contrib module provided an exportables API that was widely implemented, but was not universally supported. Drupal 8 has greatly improved on this state of affairs by providing the Configuration Management API in core. Now, configuration can be handled in a uniform and predictable way. During runtime, configuration items exist in the database, as always, but may be exported to and imported from the filesystem as needed.

These synchronization operations by default happen in the CONFIG_SYNC_DIRECTORY. The location of this directory is defined in the settings.php file. If a config sync directory is not defined when the Drupal installer runs, it will create one inside of the files directory. Because configuration files may contain sensitive information, Drupal takes measures to protect the location that the configuration files are placed to prevent a situation where an outside party might be able to read one of these files with a regular web request. There are two primary techniques employed:

  1. The name of the configuration folder is randomly generated, to make it impossible to guess the path to the configuration files.

  2. A .htaccess file is written to the directory, so that sites that use Apache, at least, will not serve files stored inside it.

While these measures provide a reasonable level of protection, an even better solution is to place the configuration files entirely outside of the web server’s document root, so that there is absolutely no way that the configuration files can be addressed. It is easy to change the location of the sync directory; this process is described in the documentation page.

Your configuration files should be committed to your git repository, so, before you move your configuration files, you should ensure that you are working with a site that is utilizing a relocated document root. An example project to do this is presented in the blog post Using Composer with a Relocated Document Root on Pantheon.

To specify a different location for your configuration files, you can redefine this variable to place your configuration above your Drupal root by adding the following code to your settings.php file:
 * Place the config directory outside of the Drupal root.
$config_directories = array(
  CONFIG_SYNC_DIRECTORY => dirname(DRUPAL_ROOT) . '/config',

On a Pantheon site, you should make sure that you add this code after the settings.pantheon.php is included; otherwise, the CONFIG_SYNC_DIRECTORY will be overwritten with the Pantheon default value. Also, you need to ensure that the configuration directory exists before you change this variable in your settings file. If you already have an extant configuration directory, you can simply git mv it to its new location.

$ git mv web/sites/default/files/config .

That’s really all there is to it. Once your configuration directory has been relocated, all configuration management operations will continue to work the same way that they always have. If you are using Drupal 8 with a relocated document root, relocating your configuration files is something that you should be doing.

Related Information:

Topics Development, Drupal Planet, Drupal