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/