Basic Configuration¶

From scratch¶

1. .gitignore¶

Default .gitignore to use on our Drupal 8 projects:

# Ignore directories generated by Composer
/drush/contrib/
/vendor/
/web/core/
/web/modules/contrib/
/web/themes/contrib/
/web/profiles/contrib/
/web/libraries/

# Ignore sensitive information
/web/sites/*/settings.php
/web/sites/*/settings.local.php

# Ignore Drupal's file directory
/web/sites/*/files/

# Ignore SimpleTest multi-site environment.
/web/sites/simpletest

# Ignore files generated by PhpStorm
/.idea/

You can add more if you need. You must not remove the defaults.

2. Create and enable shared settings¶

You have to make the site settings directory (e.g. default) and is settings.php writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default
chmod +w sites/default/settings.php

Open settings.php file in sites/default and add these lines to the end:

if (file_exists($app_root . '/' . $site_path . '/settings.shared.php')) {
  include $app_root . '/' . $site_path . '/settings.shared.php';
}

This will include the shared settings file as part of Drupal's settings file.

In sites/default create the file settings.shared.php with this code:

<?php

/**
 * Trusted host configuration.
 *
 * Drupal core can use the Symfony trusted host mechanism to prevent HTTP Host
 * header spoofing.
 *
 * To enable the trusted host mechanism, you enable your allowable hosts
 * in $settings['trusted_host_patterns']. This should be an array of regular
 * expression patterns, without delimiters, representing the hosts you would
 * like to allow.
 *
 * For example:
 * @code
 * $settings['trusted_host_patterns'] = array(
 *   '^www\.example\.com$',
 * );
 * @endcode
 * will allow the site to only run from www.example.com.
 *
 * If you are running multisite, or if you are running your site from
 * different domain names (eg, you don't redirect http://www.example.com to
 * http://example.com), you should specify all of the host patterns that are
 * allowed by your site.
 *
 * For example:
 * @code
 * $settings['trusted_host_patterns'] = array(
 *   '^example\.com$',
 *   '^.+\.example\.com$',
 *   '^example\.org$',
 *   '^.+\.example\.org$',
 * );
 * @endcode
 * will allow the site to run off of all variants of example.com and
 * example.org, with all subdomains included.
 */
$settings['trusted_host_patterns'] = array(
  '^yourprojectnamevm\.dev$',
);

Make sure to edit the setting with your host.

3. Create Dev / Stage / Prod settings¶

You have to make the site settings directory (e.g. default) writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default

In this directory create the empty files:

settings.dev.php
settings.stage.php
settings.prod.php

Open settings.php file in sites/default and add these lines at the end:

if (file_exists($app_root . '/' . $site_path . '/settings.dev.php')) {
   include $app_root . '/' . $site_path . '/settings.dev.php';
}

Open settings.dev.php file in sites/default and add these lines at the end:

$config['config_split.config_split.dev']['status'] = TRUE;

Than see Configuration Manager Dev docs

4. Create and enable local settings¶

You have to make the site settings directory (e.g. default) writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default

Copy and rename the sites/example.settings.local.php to sites/default/settings.local.php:

cp sites/example.settings.local.php sites/default/settings.local.php

This will include the local settings file as part of Drupal's settings file.

Open the settings.local.php created and add your local local host to on trusted host patterns adding these lines to the end:

$settings['trusted_host_patterns'][] = 'yourprojectnamevm.dev';

If you have more then one host (e.g. for multisite) add all of them.

Open settings.php file in sites/default and add these lines at the end:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
   include $app_root . '/' . $site_path . '/settings.local.php';
}

5. Create services.yml¶

You have to make the site settings directory (e.g. default) writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default

Copy and rename the sites/default/default.services.yml to sites/default/services.yml:

cp sites/default/default.services.yml sites/default/services.yml

6. Disable Drupal caching¶

Open settings.local.php and make sure the following line is present and uncommented to enable the null cache service, otherwise add it to the end of the file:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

Uncomment these lines in settings.local.php to disable the render cache and disable dynamic page cache:

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Open development.services.yml in the sites folder and add the following block to disable the twig cache:

parameters:
  ...
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Afterwards you have to rebuild the Drupal cache otherwise your website will encounter an unexpected error on page reload:

drush cr

Now you should be able to develop in Drupal without manual cache rebuilds on a regular basis.

Your final development.services.yml should look as follows (mind the indentation):

# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
  http.response.debug_cacheability_headers: true
  twig.config:
    debug: true
    auto_reload: true
    cache: false
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

7. Private files¶

To use private files on drupal you must edit your settings.shared.php.

You have to make the site settings directory (e.g. default) and is settings.shared.php writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default
chmod +w sites/default/settings.shared.php

Open the site settings.shared.php. Add and set the following line with a local file system path where private files will be stored:

$settings['file_private_path'] = '/var/www/yourprojectnamevm/drupal/private';

This directory must be absolute, outside of the Drupal installation directory and not accessible over the web.

Caches need to be cleared when this value is changed to make the private:// stream wrapper available to the system.

drush cr

Edit the main .gitignore file to add the private folder.

/private/

From existing configuration¶

1. .gitignore¶

Default .gitignore to use on our Drupal 8 projects:

# Ignore directories generated by Composer
/drush/contrib/
/vendor/
/web/core/
/web/modules/contrib/
/web/themes/contrib/
/web/profiles/contrib/
/web/libraries/

# Ignore sensitive information
/web/sites/*/settings.php
/web/sites/*/settings.local.php

# Ignore Drupal's file directory
/web/sites/*/files/

# Ignore SimpleTest multi-site environment.
/web/sites/simpletest

# Ignore files generated by PhpStorm
/.idea/

You can add more if you need. You must not remove the defaults.

2. Enable shared settings¶

You have to make the site settings directory (e.g. default) and is settings.php writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default
chmod +w sites/default/settings.php

Open settings.php file in sites/default and add these lines at the end:

if (file_exists($app_root . '/' . $site_path . '/settings.shared.php')) {
  include $app_root . '/' . $site_path . '/settings.shared.php';
}

This will include the shared settings file as part of Drupal's settings file.

3. Enable dev settings¶

Open settings.php file in sites/default and add the following lines at the end:

if (file_exists($app_root . '/' . $site_path . '/settings.dev.php')) {
   include $app_root . '/' . $site_path . '/settings.dev.php';
}

4. Create and enable local settings¶

You have to make the site settings directory (e.g. default) writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default

Copy and rename the sites/example.settings.local.php to sites/default/settings.local.php:

cp sites/example.settings.local.php sites/default/settings.local.php

This will include the local settings file as part of Drupal's settings file.

Open the settings.local.php created and add your local local host to on trusted host patterns adding these lines to the end:

$settings['trusted_host_patterns'][] = 'yourprojectnamevm.dev';

If you have more then one host (e.g. for multisite) add all of them.

Open settings.php file in sites/default and add the following lines at the end:

if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
   include $app_root . '/' . $site_path . '/settings.local.php';
}

5. Disable Drupal caching¶

Open settings.local.php and make sure the following line is present and uncommented to enable the null cache service, otherwise add it to the end of the file:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

Uncomment these lines in settings.local.php to disable the render cache and disable dynamic page cache:

$settings['cache']['bins']['render'] = 'cache.backend.null';
...
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Open development.services.yml in the sites folder and add the following block to disable the twig cache:

parameters:
  ...
  twig.config:
    debug: true
    auto_reload: true
    cache: false

Afterwards you have to rebuild the Drupal cache otherwise your website will encounter an unexpected error on page reload:

drush cr

Now you should be able to develop in Drupal without manual cache rebuilds on a regular basis.

Your final development.services.yml should look as follows (mind the indentation):

# Local development services.
#
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
parameters:
  http.response.debug_cacheability_headers: true
  twig.config:
    debug: true
    auto_reload: true
    cache: false
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

6. Private files¶

To use private files on drupal you must edit your settings.shared.php.

You have to make the site settings directory (e.g. default) and is settings.shared.php writable to do this. Drupal will restore permissions in a later moment:

chmod +w sites/default
chmod +w sites/default/settings.shared.php

Open the site settings.shared.php. Add and set the following line with a local file system path where private files will be stored:

$settings['file_private_path'] = '/var/www/yourprojectnamevm/drupal/private';

This directory must be absolute, outside of the Drupal installation directory and not accessible over the web.

Caches need to be cleared when this value is changed to make the private:// stream wrapper available to the system.

drush cr

Edit the main .gitignore file to add the private folder.

/private/