Install Drupal 10 content management system

Go to End

-> Top

Note

• 21/9/2024: Highlight mark settings added to layout.css.
• 11/9/2024: php uploading capacity increased.
• 26/6/2024: Setting of "state_cache" in settings.php added.
• 28/4/2024: Sections on restoring and relocating Drupal revised.
• 24/4/2024: Sections re-arranged to describe fresh installation procedures followed by upgrading procedures, instead of upgrading procedures followed by fresh installation procedures. "print.css" for printer-friendly version added. List of modules added.
• 24/1/2024: "php/8.3" used.
• 8/11/2023: TOP API and Convert Bundles installations added. Adding buttons to CKEditor revised.
• 5/11/2023: Upgrading to Drupal 10 added. Drupal 9 and before deleted.
• 21/12/2021: Bartik theme used instead of Mayo.
• 11/11/2021: Errors in updating core manually corrected.
• 5/1/2020: Problems when updating to Drupal 8.8 under php7.4 described. Some text updating.
• 9/9/2019: Composer files also copied when relocating system.ttp
• 18/7/2019: Composer configuration actions added.
• 7/7/2019: Original user-defined files and attributes kept when updating manually.
• 26/5/2019: Composer and Drush installations added. Manual core installation added. Deleting configuration file added.
• 16/5/2019: Simplified installation step added. Using new shell to restore added.
• 8/5/2019: Page on Drupal 8 withdrawn. All "/var/www/web" changed to "/var/www/html/web" because Apache2 prefers to put website files underneath "/www/web/html", and it is easier that way. Relocating Drupal 8 added. Print page stylesheet re-written.
• 18/1/2019: Updating Drupal 8 core using composer added.
• 30/9/2018: Setting CKEditor to use Mayo theme stylesheet added. Setting print page to also use Mayo theme stylesheet added. Adding custom styles added.
• 23/9/2018: "php/7.0" changed to "php/7.2".
• 3/9/2018: First created from the page on Drupal 7 after major upgrading to Drupal 8. Resolution of CKEditor table border added.

-> Top

Intro

(section revised, 5/11/2023)

Drupal is a web site content management system serving web pages to the internet.

Upgrading from Drupal 9 to 10 has been deferred because Drupal 10 has changed the default theme Bartik to Olivero front-end theme and Claro administration theme and some of the modules do not have compatible upgrades. We have been using Bartik and prefer it over those new themes.

However, Drupal 9 reached end of life on 1 Nov 2023. Our Drupal 9.5.11 was therefore upgraded to Drupal 10.1.6 on 4 November 2023. 

This page documents the procedures for a fresh Drupal 10 installation while upgrading procedures are described later. Most of the previous text about installing Drupal 8 and upgrading to Drupal 9 has been deleted because they are not useful anymore. Some old bits and pieces have been retained in case they may be useful.

-> Top

Prepare

(section revised, 5/11/2023)

(section moved to the front, 22/4/2024)

Install Apache2 web server if not already installed.

Enable Apache2 rewrite module (should have been automatically installed when installing HTTPS):

$ sudo a2enmod rewrite

Configure Apache2:

$ sudo gedit /etc/apache2/apache2.conf

Specify, keeping "<" and ">":

<Directory /var/www/>
    Options Indexes FollowSymLinks
    # AllowOverride None # replaced with next line
    AllowOverride All
    Require all granted
</Directory>

Restart Apache2 service:

$ sudo systemctl restart apache2
or
$ sudo service apache2 restart

Install MySQL server + PHP + phpMyAdmin, and create a user with database both called "drupal8". (This old name has not been changed since its creation.)

-> Top

Install Composer

(updated, 22/4/2024)

Install Composer from any where, and go to the directory under which all Drupal files will be installed. "/var/www/html" is the top one possible

$ sudo apt install composer

-> Top

Install Drupal 10

(section added, 5/11/2023)

(updated merging others, 22/4/2024)

Go to Drupal's website https://www.drupal.org/ for general reference.

Go to https://www.drupal.org/project/drupal/releases to find the latest release.

Assuming the latest is "x.y.z", execute

$ cd /var/www/html
$ composer create-project drupal/recommended-project:x.y.z "install-dir"

Change "install-dir" to a new name such as "drupal".

The folder structure will be:

/var/www/html/drupal/web
/var/www/html/drupal/web/core
(etc.)
/var/www/html/drupal/vendor

Because our website was upgraded from Drupal 9 to 10, our website used "drupal/legacy-project" structure instead of "drupal/recommended-project" structure. "drupal/legacy-project" has now been removed as an installation choice, but we keep it.

The folder structure is:

/var/www/html/web
/var/www/html/web/core
(etc.)
/var/www/html/web/vendor

"/web" in the drupal/legacy_project" structure would mean "/drupal/web" in the "drupal/recommended-project" structure.

Here we use "/web", and work from there.

Create a location for site specific files:

$ cd /var/www/html/web
$ chmod a+W sites/default
$ mkdir sites/default/files
$ sudo chown -R www-data:www-data sites/default/files

Create the initial configuration file:

$ sudo cp sites/default/default.settings.php sites/default/settings.php

Change ownership:

$ chmod a+W sites/default/settings.php

Disable a hidden file to disable re-direction of webpages:

$ cd /var/www/html/
$ mv .htaccess .htaccessx

Restart Apache2 service:

$ sudo systemctl restart apache2
or
$ sudo service apache2 restart

Open the web browser.

Go to https://localhost/web/core/install.php.

Follow the steps there:

• Choose language: English language
• Choose profile: Standard
• Setup database: MySQL
• MySQL database name, user name and password as defined above
• Advanced options
  • Host: localhost
  • Port number: 3306
  • Transaction isolation level: READ COMMITTED
• Site name: www.kctang.com.hk
• Site e-mail address: <>@kctang.com.hk
• Site maintenance username: <name of the administrator>
• Site maintenance user e-mail address: <>@kctang.com.hk
• Default country: Hong Kong S.A.R., China
• Default time zone: Asia/Hong Kong
• Check for updates automatically: Checked
• Receive e-mail notifications: Checked
• Save and continue and the website will be up and running.

Enable the hidden file:

$ mv .htaccessx .htaccess
$ cd web

Change directory and file permissions to restrict:

$ cd web
$ chmod go-w sites/default/settings.php
$ chmod go-w sites/default

Increase upload file size limit (php 8.3 used now as of 22/1/2024):

$ sudo gedit /etc/php/8.3/apache2/php.ini

Change existing capacity to:

; increased from 8M to 200M to 1000M
post_max_size = 1000M
; increased from 2M to 50M to 1000M
upload_max_filesize = 1000M
; increased from 20
max_file_uploads = 100

(capacity increased, 11/9/2024)

Restart Apache2 service after every change:

$ sudo systemctl restart apache2
or
$ sudo service apache2 restart

Edit "settings.php" file:

$ sudo nano sites/default/settings.php

Specify trusted hosts:

$settings['trusted_host_patterns'] = array(
   '^www\.kctang\.com\.hk$',
   '^kctang\.com\.hk$',
   '^localhost$',
);

Set state_cache:

$settings['state_cache'] = True;

(added, 20/6/2024)

Disable "install.php" file:

$ sudo mv core/install.php core/<some new name>

-> Top

Re-direct http path to sub-directory "web"

The default DocumentRoot in the default enabled Apache2 configuration file /etc/apache2/sites-enabled/000-default.conf is "/var/www/html/".

Web browers can access any permissible directories or files underneath the DocumentRoot. Access outside the Document Root will not be possible.

When the Drupal root directory /web is placed underneath /var/www/html such as /var/www/html/web, then https://kctang.com.hk will access the default index.html file underneath /var/www/html, but in the case of https://kctang.com.hk/web, access to those underneath /web is possible.

To re-direct https://kctang.com.hk to access /var/www/html/web directly, create a new ".htaccess" file under "/var/www/html":

$ sudo gedit /var/www/html/.htaccess

Specify:

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteBase /
  RewriteRule ^(.*)$ web/$1 [R]
</IfModule>

"^(.*)$" represents the full text from start to end after the domain name, e.g. "abc/def" in "kctang.com.hk/abc/def".

"web/$1" represents the substitution text where "$1" represents the text represented by "(.*)" with "web/" inserted before it, i.e. "web/abc/def" based on the above example. This would redirect the path to "web/abc/def".

"[R]" is to redirect the path and will show "web/" as part of the redirected path. When using "[R]", "RewriteBase /" is required to add "/" before "web/$1". Without this, "/var/www/html" will be added before "web/$1" and will cause unexpected results. This effect was discovered after many days of error discovery using "[L]".

Using [L] as suggested by many people may hide "web/" from the displayed path, and does not require the use of "RewriteBase", but some of the web pages will still show "web/" unavoidably. A mixed use with or without "web/" displayed will cause denial of access rights or redirection to external URL in some cases. Therefore, it is better to force to display "web/" using "[R]".

The following has the same effect:

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteBase /web
  RewriteRule ^(.*)$ $1 [R]
</IfModule>

-> Top

Remove "www." prefix from URL

This is not essential for using Drupal, but is adopted only to simplify.

Insert the following in /var/www/html/.htaccess after the RewriteBase line:

# Remove "www." prefix from URL
RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^ http%{ENV:protossl}://%1%{REQUEST_URI} [L,R=301]

Install drupal/bartik as a contributed theme:

$ composer require drupal/bartik

Go to Manage > Appearance to make it the default theme.

-> Top

Install Drush

(updated, 22/4/2024)

Drush is a tool to handle installation and removal of modules and themes.

Install Drush:

$ cd var/www/html/web
$ composer require drush/drush

Drush is installed under /var/www/html/web/vendor/drush/drush.

-> Top

Define Bartik theme color scheme

(section revised, 5/11/2023)

Log in as an administrator if not already in.

Choose Manage > Appearance > Settings, and define Bartik color scheme as follows:

 

Configure Bartik's css files as described below to match the preferences of this website.

-> Top

Add custom styles to Bartik theme

(section added, 21/12/2021)

(section revised, 6/11/2023)

Log in the server.

Create a "misc" directory under the Drupal root directory, and edit to create 4 new files to re-define webpage styles:

$ cd /var/www/html/web
$ mkdir misc
$ cd misc
$ nano <new file name>

Create "append-to-elements.css" file to contain:

/* the following settings added, KCTang 18/12/2021 */
body {
 margin: 0;
 color: blue;
 font-family: Arial;
}
p {
 margin: 0.2em 0 0.2em;
}
pre{
 border: 1px solid green;
 font-family: monospace;
 margin: 0.15em 0.2em 0.15em;
 padding: 0.2em;
 background-color: #f8f9fa;
 white-space: pre-wrap;
}
.widget-toc{
 display: table;
 border: 1px solid green;
 background-color: #f8f9fa;
 padding: 0.5em;
 font-size: 0.9em;
}
.hangtwice {
 margin-left: 80px;
 text-indent: -80px;
}
.hang1 {
 margin-left: 40px;
 text-indent: -40px;
}
.hang2 {
 margin-left: 80px;
 text-indent: -40px;
}
.hang3 {
 margin-left: 120px;
 text-indent: -40px;
}
.hang4 {
 margin-left: 160px;
 text-indent: -40px;
}
.hang5 {
 margin-left: 200px;
 text-indent: -40px;
}
.indent1 {
 margin-left: 40px;
}
.indent2 {
 margin-left: 80px;
}
.indent3 {
 margin-left: 120px;
}
.indent4 {
 margin-left: 160px;
}
h1,
.heading-a {
 color: blue;
 margin: 0 0 0.5em;
}
h2 {
 border: 1px solid;
#  border-bottom: 1px solid;
 color: red;
 text-align: center
}
h2.hang {
 border: 1px solid;
 margin-left: 40px;
 text-indent: -40px;
 color: red;
}
h3 {
 border-bottom: 1px solid;
 font-weight: bold;
 font-weight: normal;
 color: magenta;
}
h3.hang {
 margin-left: 40px;
 text-indent: -40px;
 font-weight: normal;
 color: magenta;
}
h4.hang {
 margin-left: 40px;
 text-indent: -40px;
}
a,
a.link {
 border-bottom: none;
}
.site-branding__name {
 font-family: "Times New Roman";
}
img {
 margin: 15px;
}
/* the following settings added, KCTang 11/2/2023 */
blockquote {
 border-left: 2px solid #bbb; /* LTR */
 background: #F7F84D;
}
blockquote:before {
 margin-right: 0;
 content: "";
}
[dir="rtl"] blockquote:before {
 content: "";
}
blockquote:after {
 content: "";
}
[dir="rtl"] blockquote:after {
 content: "";
}
/* the following settings added, KCTang 22/3/2023 */
pre{
 font-family: math;

Create "append-to-layout.css" file to contain:

/* the following settings added, KCTang 18/12/2021 */
@media all and (min-width: 851px) {
 .layout-container {
   max-width: 1920px;
 }
}

/* the following settings added, KCTang 21/9/2024 */
mark.marker-blue {
  background-color: hsl(201, 97%, 72%);
}
mark.marker-green {
  background-color: hsl(120, 93%, 68%);
}
mark.marker-pink {
  background-color: hsl(345, 96%, 73%);
}
mark.marker-yellow {
  background-color: hsl(60, 97%, 73%);
}
mark.pen-blue {
  background-color: inherit;
  color: hsl(201, 97%, 72%);
}
mark.pen-green {
  background-color: inherit;
  color: hsl(112, 100%, 27%);
}
mark.pen-red {
  background-color: inherit;
  color: hsl(0, 85%, 49%);
}

(highlight mark settings added, 21/9/2024)

Create "append-to-main-content.css" file to contain:

/* the following settings added, KCTang 18/12/2021*/
.main-content h2 {
 margin: 0.5em 0;
 font-size: 1.429em;
}

Create "append-to-text-formatted.css" file to contain:

/* the following settings added, KCTang 18/12/2021*/
.text-formatted ul,
.text-formatted ol {
 margin: 0;
 padding: 0 0 0.25em 15px; /* LTR */
}

Change to /var/www/html/web directory.

Create "append-to-bartik-css.sh" file to contain:

#!/bin/bash
cat /var/www/html/web/misc/append-to-elements.css >> /var/www/html/web/themes/contrib/bartik/css/base/elements.css
cat /var/www/html/web/misc/append-to-layout.css >> /var/www/html/web/themes/contrib/bartik/css/layout.css
cat /var/www/html/web/misc/append-to-main-content.css >> /var/www/html/web/themes/contrib/bartik/css/components/main-content.css
cat /var/www/html/web/misc/append-to-text-formatted.css >> /var/www/html/web/themes/contrib/bartik/css/components/text-formatted.css
ls -ls /var/www/html/web/themes/contrib/bartik/css

This file is to append the settings in the last 4 files to Bartik's css files to override Bartik's settings.

Execute to append whenever there is an update to Bartik:

$ cd /var/www/html/web
$ ./append-to-bartik-css.sh

Create "print.css" file to contain:

<!-- Format the printer-friendly print layout -->
<!-- created, KCTang 29/3/2024 -->
a,
a.link {
  text-decoration: none;
  border-bottom: 1px dotted;
}
a:hover,
a:active,
a:focus,
.link:hover,
.link:active,
.link:focus {
  text-decoration: none;
  border-bottom-style: solid;
}
a[href*="EndOfPage"] {
	display: none;
}
body {
  color: black;
  font-family: Arial;
  font-size: 87.5%;
  line-height: 1.5;
  margin: 50px;
  min-height: 100%;
  word-wrap: break-word;
}
del {
  text-decoration: line-through;
}
blockquote {
  border-left: 2px solid #bbb; /* LTR */
  background: #F7F84D;
  font-style: italic;
  margin: 1.5em 10px;
  padding: 0.5em 10px;
}
[dir="rtl"] blockquote {
  border-right: 1px solid #bbb;
  border-left: none;
}
blockquote:before {
  color: #bbb;
  content: "" ;
  font-size: 3em;
  line-height: 0.1em;
  margin-right: 0; /* LTR */
  vertical-align: -0.4em;
}
[dir="rtl"] blockquote:before {
  margin-right: 0;
  margin-left: 0.2em;
  content: "";
}
blockquote:after {
  color: #bbb;
  content: "";
  font-size: 3em;
  line-height: 0.1em;
  vertical-align: -0.45em;
}
[dir="rtl"] blockquote:after {
  content: "";
}
blockquote > p:first-child {
  display: inline;
}
html {
  height: 100%;
}
h1, heading-a {
  border-bottom: none;
  color: blue;
  font-size: 2em;
  font-weight: inherit;
  line-height: 1em;
  margin: 1em 0 0.5em;
  page-break-before: always;
  text-align: center;
}
h2, heading-b {
  border: 1px solid;
#  border-bottom: 1px solid;
  color: red;
  display: block;
  font-size: 1.143em;
  font-weight: inherit;
  line-height: 1.4;
  margin: 0.5em 0;
#  margin-block-start: 0.83em;
#  margin-block-end: 0.83em;
#  margin-inline-start: 0px;
#  margin-inline-end: 0px;
  text-align: center
}
h3, heading--c {
  border-bottom: 1px solid;
  color: magenta;
  font-size: 1.092em;
  font-weight: inherit;
  margin: 1em 0 0.5em;
}
h4, heading-d {
  font-size: 1.05em;
  font-weight: inherit;
  margin: 0.5em 0;
}
h5, heading-e {
  letter-spacing: 0.1em;
  text-transform: uppercase;
  font-size: 0.889em;
  font-weight: inherit;
  margin: 0.5em 0;
}
h6, heading-f {
  letter-spacing: 0.1em;
  text-transform: uppercase;
  font-size: 0.67em;
  font-weight: inherit;
  margin: 0.5em 0;
}
h1 a,
h2 a {
  border-bottom: none;
}
img {
  margin: 15px;
  max-width: 100%;
  height: auto;
}
li {
  display: list-item;
}
ol {
  list-style-type: decimal;
}
ul {
  list-style-type: disc;
}
ul,
ol,
ol ol,
ul ul {
  margin: 0;
  padding: 0 0 0.25em 1em; /* LTR */
}
[dir="rtl"] ol,
[dir="rtl"] ul,
[dir="rtl"] ol ol,
[dir="rtl"] ul ul {
  padding: 0 1em 0.25em 0;
}
mark.marker-blue {
  background-color: hsl(201, 97%, 72%);
}
mark.marker-green {
  background-color: hsl(120, 93%, 68%);
}
mark.marker-pink {
  background-color: hsl(345, 96%, 73%);
}
mark.marker-yellow {
  background-color: hsl(60, 97%, 73%);
}
mark.pen-blue {
  background-color: inherit;
  color: hsl(201, 97%, 72%);
}
mark.pen-green {
  background-color: inherit;
  color: hsl(112, 100%, 27%);
}
mark.pen-red {
  background-color: inherit;
  color: hsl(0, 85%, 49%);
}
p {
  display: block;
  margin: 0.2em 0 0.2em;
#  margin-block-start: 1em;
#  margin-block-end: 1em;
#  margin-inline-start: 0px;
#  margin-inline-end: 0px;
}
pre {
  background-color: #f8f9fa;
  border: 1px solid green;
  font-family: monospace;
  font-family: math;
  margin: 0.15em 0.2em 0.15em;
  padding: 0.2em;
  white-space: pre-wrap;
}
.align-center {
  display: block;
  margin-right: auto;
  margin-left: auto;
}
.align-left {
  float: left;
}
.align-right {
  float: right;
}
.block {
  margin: 10px;
}
.content {
  margin: 10px;
  padding: 15px;
}
.feed-icon {
  display: block;
  margin: 25px 0 0 0;
}
.field.field--name-created {
	display: none;
}
.field.field--name-title {
	display: none;
}
.field.field--name-uid {
	display: none;
}
.hangtwice {
  margin-left: 80px;
  text-indent: -80px;
}
.hang {
  margin-left: 40px;
  text-indent: -40px;
}
.hang1 {
  margin-left: 40px;
  text-indent: -40px;
}
.hang2 {
  margin-left: 80px;
  text-indent: -40px;
}
.hang3 {
  margin-left: 120px;
  text-indent: -40px;
}
.hang4 {
  margin-left: 160px;
  text-indent: -40px;
}
.hang5 {
  margin-left: 200px;
  text-indent: -40px;
}
.footerL {
  position: fixed;
  top: 0;
}
.headerL {
  position: fixed;
  bottom: 0;
}
.indent1 {
  margin-left: 40px;
}
.indent2 {
  margin-left: 80px;
}
.indent3 {
  margin-left: 120px;
}
.indent4 {
  margin-left: 160px;
}
.link {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}
.main-content {
  margin: 10px
  padding: 15px;
}
.page-title {
  font-size: 2em;
  line-height: 1em;
}
.section {
  margin: 10px;
  padding: 15px;
}
.site-branding__name {
  font-family: "Times New Roman";
}
.tabledrag-handle:hover,
.tabledrag-handle {
  border: none;
}
.text-align-center {
  text-align: center;
}
.text-align-left {
  text-align: left;
}
.text-align-right {
  text-align: right;
}
.text-align-justify {
  text-align: justify;
}
.text-formatted ul,
.text-formatted ol {
  padding: 0 0 0.25em 15px; /* LTR */
  margin: 0;
}
[dir="rtl"] .textfmedia-formatted ul,
[dir="rtl"] .text-formatted ol {
  padding: 0 15px 0.25em 0;
}
.widget-toc {
  display: table;
  border: 1px solid green;
  background-color: #f8f9fa;
  padding: 0.5em;
  font-size: 0.9em;
}
@media screen and (max-width: 37.5em) { /* 600px */
  th.priority-low,
  td.priority-low,
  th.priority-medium,
  td.priority-medium {
	display: none;
  }
}
@media screen and (max-width: 60em) { /* 920px */
  th.priority-low,
  td.priority-low {
	display: none;
  }
}
#EndOfPage {
	display: none;
}

Clear cache to reveal the effects of the new settings:

$ vendor/drush/drush/drush cr

-> Top

Add buttons to CKEditor 5

(revised, 8/11/2023)

Log in the website as an administrator.

Choose Manage > Configuration > Text formats and editors > Configure Full HTML.

Move the required buttons down to a suitable position in the active toolbar:

Include moving the Style button.

Enter a list of classes and titles as follows:

p.hangtwice|Hang Twice
p.hang1|Hang 1 
p.hang2|Hang 2
p.hang3|Hang 3
p.hang4|Hang 4
p.hang5|Hang 5
p.indent1|Indent 1
p.indent2|Indent 2
p.indent3|Indent 3
p.indent4|Indent 4
h2.hang|Head2Hang
h3.hang|Head3Hang
h4.hang|Head4Hang

"p" stands for paragraph.

".hangtwice" stands for the name of class as defined in the "css/style.css" file.

"Hang Twice" stands for the title seen when the Styles button is pressed to give a drop down menu.

Drush is installed under /var/www/html/web/vendor/drush/drush.

-> Top

Add TOC API for table of contents

(section added, 8/11/2023)

Unlike CKEditor 4, CKEditor 5 does not have table of contents for free. The previous tables of contents have to be removed page by page.

Use TOC API instead.

Go to Drupal's top folder and install drupal/toc_api:

$ cd /var/www/html/web
$ composer require drupal/toc_api

TOP API Example will automatically be installed also. TOP API is the back end. The Example actually adds the table of contents.

Enable the two modules at Manage > Extend > List.

Go to Manage > Structure > Table of contents types to see a list of example tables.

The default is the one that will be used. The other are examples.

Edit the default. Use responsive to suit mobile phones, which will show on mobile phones the title only with a drop down menu.

Change back to top maximum level to "h2". Change "Back to top" to "-> Top".

No change here.

Change numbering suffix from ") " to ". " both ending with a space.

The numbering suffice follows the numbers to the headings in the body. The numbering separator follows the numbers in the table of contents.

-> Top

Install other modules

(added, 22/4/2024)

Install the following modules using "composer require <module name as below>":

• drupal/back_to_top_with_pi
• drupal/bartik (already mentioned)
• drupal/book_link_weight
• drupal/book_tree_menu
• drupal/ckeditor
• drupal/ckeditor5_findandreplace
• drupal/ckeditor5_font
• drupal/ckeditor5_fullscreen
• drupal/ckeditor5_highlight
• drupal/ckeditor5_media_embed
• drupal/ckeditor5_show_block
• drupal/ckeditor_find
• drupal/ckeditor_font
• drupal/classy
• drupal/color
• drupal/color-color
• drupal/colorbox
• drupal/colorbutton
• drupal/convert_bundles
• drupal/core (if not already present)
• drupal/core-composer-scaffold (if not already present)
• drupal/core-project-message (if not already present)
• drupal/core-recommended (if not already present)
• drupal/core-vendor-hardening (if not already present)
• drupal/ctools_entity_mask
• drupal/entity_reference_revisions
• drupal/etc
• drupal/font_resize
• drupal/gdoc_field
• drupal/imce
• drupal/insert
• drupal/jquery_ui
• drupal/jquery_ui_effects
• drupal/pathauto
• drupal/pdf
• drupal/pdf_reader
• drupal/quick_node_clone
• drupal/toc_api
• drupal/token
• drupal/upgrade_status
• drupal/view_unpublished
• drush/drush (already mentioned)
• roave/better-reflection

Go to Manage > Entend > relevant module, and click to activate and click to configure as necessary.

Use "composer update <module name>" to update.

Use "composer remove <module name>" to remove.

If "composer remove" cannot remove the module entirely, execute:

vendor/drush/drush/drush pmu -y <module name>
vendor/drush/drush/drush cex 
(to export the settings)

-> Top

Install Convert Bundles

(section added, 8/11/2023)

When testing various table of contents modules, it was found that some would apply to the Basic Pages but not the Book Pages. This website previously used mainly Book Pages. The drupal/convert_bundles module can be used to convert a type of contents pages to another type. Generally, follow the default settings. After many trials, TOC API has been chosen for the table of contents. By that time all the Book Pages have been changed to Basic Pages. It has not been tested whether the conversion is really required in order to use TOC API.

-> Top

Update Drupal using Composer

(section added, 18/1/2019)

(simplified, 5/11/2023)

(updated, 22/4/2024)

Put site into maintenance mode:

• Select Admin > Manage > Configuration: Maintenance mode > Put site into maintenance mode > Save configuration.  

Go to the root directory of the website:

$ cd /var/www/html/web

Check for outdated modules:

$ composer show --outdated drupal/* -vvv

"-vvv" is to display what is going on.

Update Drupal core:

$ cd /var/www/html/web
$ composer update "drupal/core-*" --with-all-dependencies
(or)
$ composer update "drupal/core-*" --W

Update all:

$ composer update drupal ---vvv

Update database:

$ vendor/drush/drush/drush updatedb -vvv

Answer "yes" when asked to run specified post-update changes.

Clear cache:

$ vendor/drush/drush/drush cr -vvv

Browse the website to see that the webpages can show up successfully.

Set to release the website from maintenance mode:

• Select Admin > Manage > Configuration: Maintenance mode > unselect Put site into maintenance mode > Save configuration.

-> Top

Restore Drupal site

(section added, 8/5/2019)

(revised, 16/5/2019)

(revised, 28/4/2024)

Follow Manipulate whole database to find an old database backup of the desired time.

From Back In Time backups, find the web files backed up at a slightly later time.

The restored webpages will be based on the database while newer web files may be ignored.

Follow Manipulate whole database to:

• Back up the existing database
• Delete the existing database.

Move existing web files to another location (e.g. "oldweb"):

$ cd /var/www/html
$ sudo mv web oldweb

Follow Manipulate whole database to:

• Create a new empty database of the same name
• Import the chosen database backup to the newly created empty database.

Restore the chosen web files using Back in Time to the original directory (e.g. /var/www/html/web).

Execute

$ sudo gedit /var/www/new/web/sites/default/settings.php

For

$database['default']['default'] = array (
    'database' = '<text>'
    'username' = '<text>'
    'password' = '<text>'
    ....
);

check the various <text> to match the existing, particularly the password.

Use web browser to see whether web pages are displayed properly.

If web pages are displayed properly, the pair of database and web files match.

Execute to update database and clear caches:

$ cd /var/www/html/web
$ composer update
$ vendor/drush/drush/drush updatedb
$ vendor/drush/drush/drush cr

Resolve problems arising.

Delete "oldweb" if not to be used.

$ cd /var/www/html
$ sudo rm -r oldweb

-> Top

Relocate Drupal site

(section added, 28/4/2024)

Relocation can mean:

• Renaming the database and moving the web files.
• Keeping the database name but moving the web files.

Use phpMyAdmin to rename the database. This will be the simplest.

Alternatively:

Follow Manipulate whole database to:

• Back up the existing database
• Delete the existing database.
• Create an empty database of new name
• Import the existing database backup to the newly created empty database.

Move existing web files to another location, say "web2" under the same DocumentRoot directory "/var/www/html":

$ cd /var/www/html
$ sudo mv web web2

If a different DocumentRoot directory is used:

• Execute:

$ cd /var/www
$ sudo mkdir <new_DocumentRoot>
$ sudo mv html/web <new_DocumentRoot>            (if "web" name not changed)
(or)
$ sudo mv html/web <new_DocumentRoot>/web2       (if "web" name changed to "web2")
$ sudo cp html/.htaccess <new_DocumentRoot>

• Edit config file to change "/var/www/html" to "var/www/<new_DocumentRoot>":

$ sudo gedit /etc/apache2/sites-enabled/000-default.conf

Change the ".htaccess" file under "/var/www/html" or "var/www/<new_DocumentRoot>" as the case may be to re-direct web to access "web2" (if changed from web) directly:

$ sudo gedit /var/www/html/.htaccess
(or)
$ sudo gedit /var/www/<new_DocumentRoot>/.htaccess

Specify "web2" instead of "web":

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteBase /
  RewriteRule ^(.*)$ web2/$1 [R]
</IfModule>

Execute:

$ sudo gedit /var/www/new/web/sites/default/settings.php

For:

$database['default']['default'] = array (
    'database' = '<text>'
    'username' = '<text>'
    'password' = '<text>'
    ....
);

check the various <text> to match the new, particularly the database name and password.

Use web browser to see whether web pages are displayed properly.

If web pages are displayed properly, the relocation is successful.

Execute to update database and clear caches:

$ cd /var/www/html/web2
(or)
$ cd /var/www/<new_DocumentRoot>/<web or web2>
$ composer update
$ vendor/drush/drush/drush updatedb
$ vendor/drush/drush/drush cr

Resolve problems arising.

-> Top

Delete left-over module configuration files

(section added, 26/5/2019)

If a left-over configuration setting file is reported when a module is re-installed, execute to delete it:

$ cd /var/www/html/web
$ vendor/drush/drush/drush config:delete '<name of configuration file to delete>'

-> Top

Upgrade Drupal 9 to 10

(section added, 5 Nov 2023)

The upgrading command as given above is very simple, but the reality is not that simple because there can be many errors due to incompatible modules and themes as well as locking to some previous releases, resulting in the inability to upgrade. There are many other websites describing how to solve the upgrading problems, but the solutions mostly cannot work. After about 12 hours of trials and errors over two days, the upgrading was finally successful. The following records the procedures used (based on memory).

Go to Drupal's top folder and install drupal/upgrade_status:

$ cd /var/www/html/web
$ composer require drupal/upgrade_status

Go to Manage > Reports > Upgrade status.

Get the list of modules and themes which should be updated for Drupal 10.

Get the list of modules and themes which are incompatible with Drupal 10 or no longer used.

Go to Manage > Extend or > Appearance to update or remove modules and themes.

Alternatively, use composer to update or remove:

$ composer require <group name>/<name>
or
$ composer require <group name>/<name>:<add version number as necessary>
or
$ composer remove <group name>/<name>

Go to Manage > Configuration > Text formats and editors to change the text editor from CKEditor to CKEditor 5.

Change back to CKEditor if errors occur when saving the change. Remove those not acceptable menu icons. Change back to CKEditor 5 until the change is successfully saved.

Remove drupal/upgrade_status because the installed version is not compatible with Drupal 10.

$ composer remove drupal/upgrade_status

Update all files and settings to the current version:

$ composer update --with-all-dependencies
$ vendor/drush/drush/drush updatedb

"--with-all-dependencies" can be abbreviated as "-W".

Enable write access (not tested whether this is really necessary):

chmod 777 web/sites/default
chmod 666 web/sites/default/*settings.php
chmod 666 web/sites/default/*services.yml

Install Drupal 10 but without updating, and edit composer.json (see alternative below):

$ composer require drupal/core-recommended:10.1.6 drupal/core-composer-scaffold:10.1.6 drupal/core-project-message:10.1.6 --no-update
$ nano composer.json

Change the following line to state the new release number (it is an important step in this order, otherwise, upgrading will report incompatible new release or locked old releases):

"drupal/core": "10.1.6",

Upgrade now based on the newly specified release:

$ composer update --with-all-dependencies

Alternatively, the following command may work instead of the above command with "--no-update" option and the update command:

$ composer require "drupal/core:9.5.11 as 10.1.16" --no-update && composer update

However, the following line in composer.json still needs to be changed as such afterward.

"drupal/core": "10.1.6",

Update drush and update the database

$ composer require drush/drush
$ vendor/drush/drush/drush updatedb

The updatedb command may report post-update changes. Generally answer "Yes" to accept the changes.

The upgrading should be successful.

Restore read-only access:

chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml

Install drupal/bartik as a contributed theme:

$ composer require drupal/bartik

Go to Manage > Appearance to make it the default theme.

Add back any compatible modules previously deleted due to incompatibility.

Go to Manage > Reports > Status report to see what errors arise.

It may remind to download colorbox-master. Download and extract it to a different name as /var/www/html/web/libraries/colorbox.

It may also remind to download DOMPurify-main. Download and extract it. Move its "dist" directory to become /var/www/html/web/libraries/dompurify/dist.

Some modules are related to CKEditor, they have to be removed before CKEditor can be removed. Some of them can be re-installed after the removal of CKEditor and automatically linked to CKEditor 5.

End of Page

-> Top