unlcms / project-herbie Goto Github PK

View Code? Open in Web Editor NEW

5.0 8.0 6.0 4.14 MB

Drupal 10 implementation at the University of Nebraska–Lincoln

Home Page: https://cms.unl.edu

License: GNU General Public License v2.0

PHP 40.89% CSS 10.43% Twig 47.55% JavaScript 1.13%

drupal php drupal10 unlincoln cms higher-education highered

project-herbie's Introduction

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:

Automated
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:

web/profiles/herbie/includes/settings.php.inc which is committed to the repo.
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:

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.)
Consider creating a new Feature for a package of configuration.
Use drush config:set to change a config value. An example is drush config:set unl_user.settings username_format myunl.
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.

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

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

Set up a cron job on the server to execute php web/modules/contrib/unl_multisite/cron.php on a regular basis.
Ensure the MySQL/MariaDB database user for the default site has privileges to create new databases.
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

project-herbie's People

Contributors

Stargazers

Watchers

Forkers

ericras nishanthvangara sarongebre sujanshresthanet acoleman 10corp

project-herbie's Issues

Update .gitignore to ignore .vscode and .lando.yml

Update unl_five

Update unl_five to include unlcms/unl_five#7

Add/Enable Entity Embed module

Add Linkit module; Provide Linkit profile for Standard text format

Install CTools module

https://www.drupal.org/project/ctools

Update Drupal Core 8.7.0-beta1 from 8.7.0-alpha2

Define entity browser

Define an entity browser that allows

Selection of existing media (images and remote videos)
Upload of new media (images and remote videos)

Install Admin Toolbar module

https://www.drupal.org/project/admin_toolbar

Enable the following modules/sub-modules:

admin_toolbar
admin_toolbar_links_access_filter
admin_toolbar_tools

File Upload limitations / path strategy

File Upload limitations

What file upload limitations do we want to implement for File media files and Image media files?

Max file size
Allowed formats
Min/max resolution (images only)

I think we should have some max file size. I also think we should have a max resolution. I've used 5000x5000px in the past on projects. If there are too many pixels, that can cause the server to choke.

The default allowed formats are as follows:

File
-- txt, doc, docx, pdf
Image
-- png, gif, jpg, jpeg

Path strategy

The default path uses tokens and is [date:custom:Y]-[date:custom:m]. Since these files are managed, it's not critical that we namespace them; avoiding collisions is more important. That said, I think we should use public: //media/file/[namespace collision avoidance strategy] and public: //media/image/[namespace collision avoidance strategy], respectively. Core uses [date:custom:Y]-[date:custom:m] to avoid filename collisions. I'd like to discuss this with the team.

Evaluate use of Fences module

I've used Fences on most of my recent Drupal projects, and it is pretty convenient to clean up field-level markup with a UI setting instead of overriding individual template files.

https://www.drupal.org/project/fences

Add and configure CKeditor

Install Block Type Templates

https://www.drupal.org/project/block_type_templates

Patched with the following:
Support for View Modes
https://www.drupal.org/project/block_type_templates/issues/3018307

Review Webform Access Tab

Currently, we have removed the Access tab in Webform (both on elements and on the form). We should revisit this issue when time permits.

Originally posted by @ericras in #9 (comment)

The Access tab is scary and removing it at this time is ok. Ideally, someone with permission to edit the form would have access to the "Create submissions->Roles" portion of that page. People frequently use that option in D7 to limit submissions to people with a UNL login (authenticated users).

Meta: Site management tools functional

This is an umbrella that is somewhat dependent on whether we're using Aegir or not.

Regardless, there are some things that need porting from 7 like referencing the "main" site for the users who are administrators

Install Pathauto module

https://www.drupal.org/project/pathauto

Determine config import/export workflow

How do we accomplish the "distro" config workflow where a site's custom config (site title, custom content types, webforms) exists alongside centrally managed config from this project?

Enable and Configure Config Split/Config Ignore

Create unlcms/project-herbie-composer-plugin

The sole purpose of this package is to install webflo/drupal-finder and symfony/filesystem at the beginning of an installation so they can be used in \DrupalProject\composer\UnlScriptHandler.

Define File Media Type

Update Drupal Core 8.7.0-beta2 from 8.7.0-beta1

Release notes: https://www.drupal.org/project/drupal/releases/8.7.0-beta2

Add oomphinc/composer-installers-extender composer package

https://packagist.org/packages/oomphinc/composer-installers-extender

The composer-installers-extender is a plugin for Composer that allows any package to be installed to a directory other than the default vendor/ directory within the repo on a package-by-package basis. This plugin extends the composer/installers plugin to allow any arbitrary package type to be handled by their custom installer and specified explicitly in the "installer-paths" mapping in the "extra" data property.

This will allow us to install the Webform third-party libraries in web/libraries. I need this #9, so it'll get committed and reviewed in that pull request.

Extend Core to Support Custom oEmbed providers

The following issue is a must-have:
Alter the oEmbed provider list
Patch is submitted

The following issue is a would-be-nice:
Allow site builders to enable oEmbed providers
Patch is submitted

I'm good deploying the first patch. The second patch is subject to substantive reworking, so I think until it's committed, we use hook_media_source_info_alter() instead.

Define Image Media Type

Set up Layout Builder and create DCF/UNL Layouts

~~Add config and theme them.~~

~~This is a meta issue as this may be better broken up (into a carousel issue, grid layouts issue, and on and on)~~

Meta: Content Types

Install Menu Block module

https://www.drupal.org/project/menu_block

Enable core Media Library module

Install Allowed Formats module

https://www.drupal.org/project/allowed_formats

RIP Better Formats

Install Layout Builder Restrictions

https://www.drupal.org/project/layout_builder_restrictions

Add missing files to /config/sync

The following files are automatically generated in /config/sync:

config/sync/.htaccess
config/sync/README.txt

Let's add them to version control so they don't show up as untracked files.

Install Token module

https://www.drupal.org/project/token

Create unl_utility custom module

A unl_utility module will contain utility functions that can be used across Project Herbie.

Add/Enable Entity Browser module

Standardize Field Namespaces

We should standardize field name spaces.

Proposal

[optional_custom_designator]_[entity_type_abbreviation]_[bundle_abbreviation]_[name]

Proposed entity type abbreviations (max two characters):

b = block
c = reserved (see Namespace Reserved for Customizations below)
ee = External Entity
n = node
m = media
p = paragraph
u = user

Proposed bundle abbreviations (max five characters):

Blocks
- html = HTML Code
- accrd = Accordion
- card = Card
- cdcir = Card + Circle Image
Nodes
- aprog = Academic Program
- bpage = Builder Page
- news = News
- person = Person
Media
- image = Image
- file = File
- rvid = Remote Video
Paragraph
- Use the host entity's entity type abbreviation + bundle abbreviation + field abbreviation
- E.g. For a paragraph attached to the Accordion block as an Item field, the prefix would be "p_b_accrd_item_". The paragraph's title field would be "p_b_accrd_item_title".

Examples:

b_html_body = Body field on the HTML Code bundle of the Block entity type
m_file_size = Size field on the File bundle of the Media entity type
n_person_name = Name field on the Profile bundle of the Node entity type

Field machine name prefix

It's possible to modify the field prefix used for machine names:

Field prefix in Field UI is configurable

I propose we remove the field prefix for fields created via the UI, which will free up six characters.

Namespace Reserved for Customizations

We anticipate customizations being built atop this distribution. I propose we reserve the c namespace to avoid future collisions.

c_n_food_group = Food Group field on the custom Food bundle of the Node entity type

Commit Patches to Repository

Files (including patch files) that are attached to issues on Drupal.org can be deleted. This has happened before. This issue seeks to store copies of all patches used by this project to this repository. composer.json should be updated to apply patches from this repository.

Determine and implement multisite configuration

Classic multisite like we did in Drupal 7

or....

Aegir

Configuration Read-only mode

https://www.drupal.org/project/config_readonly
https://www.drupal.org/project/config_ignore_readonly

Add to the 'production' settings:
$settings['config_readonly'] = TRUE;

Install ImageMagick module

https://www.drupal.org/project/imagemagick

version 8.x-2.4 instead of 8.x-1.0-alpha

Rename layout builder "sections" to "bands"

Layout builder uses the term "sections", and we use the term "bands". This issue proposes using the String Overrides module to modify the UI to replace references to "sections" with references to "bands".

D8 ships with an Interface Translation module that builds on the multi-lingual capabilities of D8 core. That said, I think this is overkill for what we need. String Overrides tests successfully in D8 for me. That said, there is no D8 release, and it's been unsupported for a long time with no commits in about 13 months. We'd want to secure maintainership.

Define Remote Video Media Type

Meta: Custom Block types

Add config and theme them.

This is a meta issue as this may be better broken up (into a carousel issue, grid layouts issue, and on and on)

Install Field Group module

https://www.drupal.org/project/field_group

Strip sites/default/files path from files like we did in 7?

Meta: Site migration from Drupal 7

If we're supporting a DB to DB migration we'll probably need some custom code that handles inputting/obscuring the password for the database

Add Builder Page permissions

Currently, permissions for the Builder Page content type are not assigned to the administrator role.

Evaluate A11yFirst

https://github.com/a11yfirst/

Create settings.php.inc

Create a settings.php.inc file to include code that we want executed in settings.php. This include file will live at profiles/herbie/includes/settings.php.inc. The default.settings.php file will be patched to include settings.php.inc. This will allow us to modify the included code without needing to update the various settings.php files that will exist in our multi-site installation.