Drupal 10 at UNL (Project Herbie)

A multisite installation hosted at https://cms.unl.edu/ developed by the Digital Experience Group and supported by DXG and ITS.

Requirements

See Drupal System Requirements

While it is possible to run Drupal on a variety of web servers, database servers, etc., the officially supported configuration at UNL is as follows:

• Linux (any modern, supported distribution)
• PHP 8.1 or greater
• Apache 2.4 or greater
• MariaDB 10.6 or greater

Latest verified working configuration:

• PHP 8.1.10
• Apache 2.4.54
• MariaDB 10.7.3

Composer, PHP's dependency manager, is necessary to install this project. See Install Composer.

Note: The instructions below refer to the global composer installation. It may be necessary to replace composer with php composer.phar (or similar).

DDEV Support

See the DDEV-README.md file in this project.

Production Environment & Deployment Procedure

See the important notes in the DXG Wiki.

Installation

Navigate to the project root and install the project:

composer install

Install the UNLedu Web Framework

The unl_five theme requires the UNLedu Web Framework.

There are two methods to install the UNLedu Web Framework:

1. Automated
2. Manual

Automated

The unl/wdntemplates package is already downloaded to /vendor/unl/wdntemplates. Run the following command:

composer install-wdn

This command will create a symlink of /vendor/unl/wdntemplates/wdn at /web/wdn.

The wdntemplates package is a Node.js project that uses Grunt. This command will also install the Node.js project and run the default Grunt task.

To receive upstream updates, navigate to vendor/unl/wdntemplates and run git pull.

Manual

Download the UNLedu Web Framework sync set to /web/wdn.

Install Drupal

cp web/sites/default/default.settings.php web/sites/default/settings.php
cp web/sites/all/settings.php.sample web/sites/all/settings.php

Edit web/sites/all/settings.php and set the LDAP password.

Navigate to http://example.unl.edu/project-herbie/web/ (or set up a virtual host, cms-local.unl.edu is the recommended name) in your browser. (See Installing Drupal)

When asked to select an Installation Profile, select Use existing configuration.

Decide if you want to run a multisite installation. (See "Running Multisite" below.)

Common Settings for All Sites

Settings that apply to all sites can be included in one of two places:

1. web/profiles/herbie/includes/settings.php.inc which is committed to the repo.
2. web/sites/all/settings.php which is not committed and is appropriate for sensitive info or environment specific overrides to things set in (1). (A sample value can be committed to web/sites/all/settings.php.sample.)

Upgrading Drupal Core (or a module)

Run this on a development site and commit composer.json, composer.lock, and any changes to config/sync. The process is the same for a module, just change the project in the first composer command.

composer update "drupal/core-*" --with-all-dependencies
drush updatedb
drush cache:rebuild
drush config:export

Run on a deployment after updating code base:

composer install

Run on all sites:

drush updatedb
drush cache:rebuild

Configuration Management

This project uses Drupal Configuration Management to store the present/base/main configuration of a new site.

After making changes, use drush config:export to export config to config/sync and commit. This config is used during a site installation to instantiate a site.

Multisite-wide Config Changes

Important: Never use drush config:import. This multisite environment is not a single site that can have all of its configuration captured in config/sync. Each site may have custom content types and other configuration that would be overwritten/deleted by a config import. As noted previously, config/sync is only used as a "distribution install profile" during the creation of a new site.

Once again, with feeling, Never use drush config:import.

Options to deploy a configuration setting across sites:

1. First check if the setting is part of a Feature. (Is the State clean on admin/config/development/features?) If not, update the Feature. (See "Features" section below.)
2. Consider creating a new Feature for a package of configuration.
3. Use drush config:set to change a config value. An example is drush config:set unl_user.settings username_format myunl.
4. Alternatively, a non-editable config value (one that end-users shouldn't be able to change) can be set in /profiles/herbie/includes/settings.php.inc and committed.

Config Split

This project uses Config Split to manage configuration among production, stage, and development. Certain modules, such as Twig Xdebug and Config Inspector are only enabled on development.

In the development config split, a number of settings are enabled, disabled, or modified: Caching is disabled; Twig caching is disabled and Twig autoloading is enabled; debug cacheability headers are enabled; CSS and JS aggregation is disabled; and file permission hardening is disabled. See /profiles/herbie/includes/settings.php.inc for more details. These settings can be overridden in settings.local.php.

Drush

Drush can be run on the default site:

vendor/bin/drush <drush-commands>

or on a specific site:

vendor/bin/drush -l https://cms-local.unl.edu/multisite1/ <drush-commands>

or on all sites in a multisite installation:

php drush-all-sites.php <drush-commands>

Features

Are written to web/modules/custom/features and part of the herbie feature bundle.

Updating a Feature

In a development site, make the changes, bump the Version on admin/config/development/features/edit/herbie_FEATURE and click Write. Then commit changes.

Updating Multisite sites with the Feature update

Deploy changes. Then run php drush-all-sites.php fim herbie_FEATURE where herbie_FEATURE is the name of the feature.

Installing & Running Multisite

The unl_multisite module provides a web interface to run a Drupal multisite setup so additional sites can exist in subdirectories such as http://example.unl.edu/site2. (This is not required to run the base site installation as a single site.)

Much of the setup that is detailed in the unl_multisite module's README file has been done in this project with Composer scripts. The following is what needs to be done manually.

1. Create these files from the provided samples:

cp web/sites/example.sites.php web/sites/sites.php
cp web/.htaccess-subsite-map.txt.sample web/.htaccess-subsite-map.txt

2. Add the following line to your Apache's configuration file (httpd.conf) where <DRUPAL_ROOT> is the file system path to the Drupal web root. Restart Apache afterward.

RewriteMap drupal_unl_multisite txt:<DRUPAL_ROOT>/.htaccess-subsite-map.txt

3. Set up a cron job on the server to execute php web/modules/contrib/unl_multisite/cron.php on a regular basis.

4. Ensure the MySQL/MariaDB database user for the default site has privileges to create new databases.

5. Enable the UNL Multisite module on the default site. It should only be enabled on the default site.

Multisite Troubleshooting

• Drush and MariaDB 10.7+ don't work with a database port set if the host is localhost. If you are using localhost for the host, clear the port setting in settings.php.

Installing ImageMagick

• If you do not have ImageMagick software installed on your device, you can do so using the follwing commands. This software is necessary to process/add images.

brew install imagemagick
brew install ghostscript

For more infromation regaridng installation go to https://imagemagick.org/script/download.php