Install Drupal 9 content management system

Go to End

Contents

Note

  • 21 Dec 2021: Bartik theme used instead of Mayo.
  • 11 Nov 2021: Errors in updating core manually corrected.
  • 5 Jan 2020:  Problems when updating to Drupal 8.8 under php7.4 described. Some text updating.
  • 9 Sep 2019: Composer files also copied when relocating system.
  • 18 July 2019: Composer configuration actions added.
  • 7 July 2019: Original user-defined files and attributes kept when updating manually.
  • 26 May 2019: Composer and Drush installations added. Manual core installation added. Deleting configuration file added.
  • 16 May 2019: Simplified installation step added. Using new shell to restore added.
  • 8 May 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 Jan 2019: Updating Drupal 8 core using composer added.
  • 30 Sep 2018: Setting CKEditor to use Mayo theme stylesheet added. Setting print page to also use Mayo theme stylesheet added. Adding custom styles added.
  • 23 Sep 2018: "php/7.0" changed to "php/7.2"
  • 3 Sep 2018: First created from the page on Drupal 7 after major upgrading to Drupal 8. Resolution of CKEditor table border added.

Intro

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

The latest version is Drupal 9. The main text below is about installing Drupal 8 with supplementary notes on upgrading to Drupal 9. The procedures described have not been proven with a fresh installation of Drupal 9 but may be quite similar.

(paragraph added, 20 Sep 2020)

Prepare

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 + PHP5 + phpMyAdmin, and create a user with database both called "drupal8".

Co-exist with Drupal 7

Change "web" below to "web2" to create another set of directories to co-exist with Drupal 7 currently using "web", otherwise, just use "web".

Install Drupal 8

Change "8.x.x" to "9.x.x" in case of Drupal 9.

(paragraph added, 20 Sep 2020)

Download the latest Drupal 8.x.x (filename drupal-8.x.x.tar.gz) from https://www.drupal.org/project/drupal, usually to own "Downloads" directory.

Use the file manager to extract the contents of the compressed file under the "Downloads" directory as "drupal-8.x.x".

Create a directory for Drupal but using a directory name of "web":

$ sudo mkdir /var/www/html/web
$ cd /var/www/html/web
$ sudo mv /home/<own account name>/Downloads/drupal-8.x.x/* .
$ sudo ls -la /home/<own account name>/Downloads/drupal-8.x.x
$ sudo mv /home/<own account name>/Downloads/drupal-8.x.x/.* .
(move hidden files, which may give an error message)
$ sudo ls -la                                                
(check moved files as intended)
$ sudo ls -la /home/<own account name>/Downloads/drupal-8.x.x
(should be empty)

Do it in one step instead of the above:

$ cd /var/www/html
$ sudo wget https://ftp.drupal.org/files/projects/drupal-8.x.x.tar.gz  
(change "8.x.x" to the version number)
$ tar -xzf drupal-8.x.x.tar.gz 
("sudo" not used so that user instead of "root" will become owner) 
$ mv drupal-8.x.x web

(simplified step added, 15 May 2019)

(revised, 26 May 2019)

("sudo" not used, 7 July 2019)

Create a location for site files:

$ cd /var/www/html/web
$ sudo mkdir sites/default/files

(change directory added, 5 January 2020)

The latest recommendation is to install Drupal using Composer. See https://www.drupal.org/docs/develop/using-composer/starting-a-site-using-drupal-composer-project-templates.

There are two templates:

  • drupal/recommended-project which is recommended by Drupal. This template requires an additional level of directory, such as /var/www/html/drupalroot/web instead of /var/www/html/web. 
  • drupal/legacy-project which uses the same directory structure as the downloadable compressed file. Since the existing installation is based on the downloadable compressed file, this structure is continued to be used, and Composer is only used for updating as described later.

(two paragraphs added, 20 Sep 2020)

Change ownership:

$ sudo chown www-data:www-data sites/default/files

Create the initial configuration file for the default site:

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

Change ownership:

$ sudo chown www-data:www-data sites/default/settings.php

Restart Apache2 service:

$ sudo systemctl restart apache2
or
$ sudo service apache2 restart

Complete the Drupal Installation through a Browser by pointing to http://localhost/web, and follow the instructions there, using:

(not .../web/install.php, 8 May 2019)

  • Choose language: English language
  • Choose profile: Standard
  • Setup database: MySQL
  • MySQL database name, user name and password as defined above
  • 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
  • Receive e-mail notifications

Change directory permissions:

$ sudo chmod 555 sites/default
$ sudo chmod 444 sites/default/settings.php

Permit uploading of files (similar change for modules and themes not required, they use ftp upload)

$ sudo chown www-data:www-data -R sites/default/files

Increase upload file size limit:

$ sudo gedit /etc/php/8.1/apache2/php.ini
(change "8.1" to the current version number)

(Changed to "8.1", 17 Aug 2022)

Change existing to:

post_max_size = 200M
upload_max_filesize = 50M
max_file_uploads = 100

Restart Apache2 service:

$ sudo systemctl restart apache2
or
$ sudo service apache2 restart

Edit "settings.php" file:

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

specify trusted hosts:

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

Disable "update.php" file:

$ sudo mv /var/www/html/web/update.php /var/www/web/<some new name>

Migrate from Drupal 7 (as of 21 February 2018)

Log in as an administrator if not already in.

Choose Manage > Extend > Book module under Core > Install at the bottom, to allow users to create and organize related content in an outline.

Choose Manage > Extend > Statistics module under Core > Install at the bottom, to log content statistics.

Similarly, enable modules in Drupal8 that are enabled in Drupal7.

Click open the explanatory note of "Statistics". Select Configure > Count content views > Save configuration > Continue.

Choose Manage > Extend > Migrate, Migrate Drupal and Migrate Drupal UI modules under Core (Experimental) > Install at the bottom, to allow users to create and organize related content in an outline.

Click open the explanatory note of Migrate Drupal UI. Choose Configure > Continue > maintenance mode > Put site into maintenance mode > Save configuration.

Move web page back to the Upgrade page. Choose Continue.

Under SOURCE DATABASE, enter: 

  • Database host: localhost
  • Database name: drupal7
  • Database username: drupal7
  • Database password: <>

Under SOURCE FILES, assuming under "oldweb" enter:

  • /var/www/oldweb

Resolve the following problems found:

  • Some uploaded files have not been migrated. Execute "sudo cp /var/www/<oldweb>/sites/default/files/* /var/www/html/web/sites/default/files" to copy the files over (not the sub-directories).
  • The Main menu used in Drupal 7 has been migrated with a machine name called "main-menu" but the machine name used in Drupal 8 is called "main". This is incompatible. Although the menu structure is the same, the contents cannot be displayed. There is also an error message saying that the main-menu index has a problem. Add another menu under "Manage > Structure > Menus". Still at there, select "Edit menu" against the migrated Main menu to edit the individual menu items. Change the "Parent link" from the migrated Main menu to the newly added menu so as to empty the migrated Main menu. This may help remove the indexing problem. The contents can be displayed using the newly added menu. If things go fine and it is preferred to use the true Main menu, move the items back from the newly added menu to the Main menu, which should now use the correct machine name. The foregoing is based on memory. During the problem solving endeavour, mySQL has been accessed to delete references to "main-menu", but it is not sure whether this is really essential.
  • The Book menu has not been migrated and will need build-up from scratch.
  • The previously used theme has not been migrated. Download and install the desired theme under Manage > Appearance. Set up with reference to the original setting.
  • Many modules have not been migrated. Download and install them from scratch under Manage > Extend. Not all modules are available for Drupal 8.
  • Some modules (e.g. CKEditor Color Button) require the creation of a "libraries" directory under the Drupal root directory.
  • Some modules require the downloading of files at the server (i.e. not the web) and putting the unzipped file directory under the "libraries" and "vendor" directories. Some even require a sub-directory under "libraries", e.g. "CKEditor Find" module requires "... libraries/ckeditor/plugins".

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 http://kctang.com.hk will access the default index.html file underneath /var/www/html, but in the case of http://kctang.com.hk/web, access to those underneath /web is possible.

To re-direct http://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>

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]

Permit redirection to external URL

This section would not be required if the path redirection is properly defined. This appears to be not required because the core has been replaced after this section was written, with the two lines unchanged but without problem caused.

Redirecting between a path with or without "web/" will be treated as a redirection to external URL. Drupal 8 does not allow redirection to external URL by default.

To allow:

$ sudo gedit /var/www/html/web/core/lib/Drupal/Core/EventSubscriber/RedirectResponseSubscriber.php

change lines 7 and 74 from:

use Drupal\Core\Routing\LocalRedirectResponse;

$safe_response = LocalRedirectResponse::createFromRedirectResponse($response);

to:

use Drupal\Core\Routing\TrustedRedirectResponse;

$safe_response = TrustedRedirectResponse::createFromRedirectResponse($response);

Handle CKEditor module

CKEditor is a WYSIWYG editor for Drupal.

For Drupal 7, CKEditor is a single optional module. The module is pre-built to contain the desired plugins under the CKEditor web site before being installed under Drupal.

For Drupal 8, CKEditor is core module but with trimmed down features. To add back those features, individual add-on modules from the Drupal website and their corresponding CKEditor plugin files from CKEditor web site have to be installed. Not all previous features have CKEditor Drupal 8 add-on modules available.

The downloaded plugin file directories need to be unzipped under the "libraries" directory . Some even require more than one sub-directory under "libraries", e.g. "CKEditor Find" module requires "... libraries/ckeditor/plugins".

Install the CKEditor "libraries" module (not the same as the libraries directory mentioned above) because some CKEditor modules require this to work.

Not all CKEditor Drupal 8 add-on modules could be installed successfully. The usual unsuccessful phenomenon is that, after installation of the modules and the related plugin directories, the icons newly made available for the editing menu are blank or do not contain the full text. If they are added to the CKEditor editing menu, the menu cannot be displayed when a page is clicked open for editing. After a lot of trial and errors, it has now been found that the cause of the problem sis actually very simple. when the corresponding plugin directories are downloaded and added to the libraries directory, only the owner is permitted to read and write. By permitting the group and others to read, the problems are solved. The command is: (revised 3 Sep 2018) 

$ sudo chmod 755 /var/www/html/web/libraries/<plugin directory name>

 

Change from Mayo theme to Bartik theme

(section added, 21 Dec 2021)

The Mayo theme has been used for this website from the beginning but has not been maintained for use with Drupal 9. The theme has therefore been changed to the Bartik theme, which is a core theme provided by Drupal.

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. The configurations described further below in relation to the Mayo theme are not applicable to the Bartik theme. 

Add custom styles to Bartik theme

(section added, 21 Dec 2021)

Log in the server.

Open with file manager the following file, and edit:

/var/www/html/web/core/themes/bartik/css/base/elements.css

Add the following at the end of the file to override the existing settings:

/* the following settings added, KCTang 18/12/2021 */

body {
  margin: 0;
  color: blue;
  font-family: Arial;
}
p {
  margin: 0 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-bottom: 1px solid;
  color: red;
}
h2.hang {
  margin-left:40px;
  text-indent:-40px;
  color: red;
}
h3 {
  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;
}

Save and exit.

Additional text style choices have been added. Add style buttons to CKEditor as described later below.

Open with file manager the following file, and edit:

/var/www/html/web/core/themes/bartik/css/components/main-contents.css

Add the following at the end of the file to override the existing settings:

/* the following settings added, KCTang 18/12/2021*/

.main-content h2 {
  margin: 0.5em 0;
  font-size: 1.429em;
}

Save and exit.

Open with file manager the following file, and edit:

/var/www/html/web/core/themes/bartik/css/components/text-formatted.css

Add the following at the end of the file to override the existing settings:

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

Open with file manager the following file, and edit:

/var/www/html/web/core/themes/bartik/css/layout.css

Revise part of the settings as follows:

@media all and (min-width: 851px) {
  .layout-container {
#    max-width: 1290px;
    max-width: 1920px; /* revised by KCTang 18/2/2021 */
  }
}

Save and exit.

Clear cache at the command prompt to reveal the effects of the new settings:

$ vendor/drush/drush/drush cr

Note that the Bartik theme files are provided underneath the "core" directory. The files there will be overwritten when there is an upgrading of the core. This would cancel the change to Bartik.

Create a directory for "misc" outside the "core" directory to contain a backup of the changed files, and re-use them after upgrading of the core.

Execute to create "misc" directory:

$ mkdir /var/www/html/web/misc
$ cd /var/www/html/web/
$ cp core/themes/bartik/css/base/elements.css  misc
$ cp core/themes/bartik/css/components/main-content.css misc
$ cp core/themes/bartik/css/components/text-formatted.css misc
$ cp core/themes/bartik/css/layout.css misc

Log out the server.

Resolve CKEditor table border conflicting Mayo theme

(section added, 3 Sep 2018)

When the Mayo theme is used for web page appearance, a table created with CKEditor and seen while editing can only have the outer border lines displayed on the published page. The inner border lines disappear. To display the inner border lines, execute:

$ sudo gedit /var/www/html/web/themes/mayo/css/style.css

Uncomment the following border-style and border-width lines so as not to interfere with those set by CKEditor:

table tr td {
   padding: 4px 6px;
#  border-style: solid;
#  border-width: 0px;
}

table tr th {
#  border-style: solid;
   padding: 4px 6px;
#  border-width: 0px;
   border-right-width: 0px;
}

When creating or modifying a table with CKEditor, set the border size to 1, 2, ... to see the border lines. Set the border size to 0 to hide the border lines.

Set CKEditor to use Mayo theme stylesheet

(section added, 30 Sep 2018)

Edit Mayo theme's info setting:

$ sudo gedit /var/www/html/web/themes/mayo/mayo.info.yml

Insert a new line "- css/style.css":

ckeditor_stylesheets:
  - css/ckeditor-iframe.css
  - css/style.css

Save and exit.

Set print page to also use Mayo theme stylesheet

(section added, 30 Sep 2018)

(re-written to use symbolic link, 8 May 2019)

Execute to find the text "misc/print.css" which is the name of the stylesheet for the default printer-friendly printing:

$ cd /var/www/html/web
$ grep -R misc/print.css

This will show a number of directories containing files named "book-export-html.html.twig" containing:

<link type="text/css" rel="stylesheet" href="misc/print.css" />

The relevant directory is  /var/www/html/web/core/themes/stable/templates/layout.

"misc/print.css" should be corrected to "core/misc/print.css". However, even if this file is absent, it only means that the stylesheet would not apply. The page can still be displayed though without the desired style. To use Mayo theme stylesheet, the name should be changed.

However, the files underneath the "core" directory will be overwritten when there is an upgrade of the core. This would cancel the change to Mayo.

Instead, create a directory for "misc/print.css" outside the "core" directory so as not to be affected.

Execute to create 

$ mkdir /var/www/html/web/misc
$ sudo ln -s /var/www/html/web/themes/mayo/css/style.css  misc/print.css

This will create a symbolic link to the Mayo theme stylesheet which will then apply.

Add custom styles to Mayo theme

(section added, 30 Sep 2018)

Edit Mayo theme's css setting:

$ sudo gedit /var/www/html/web/themes/mayo/css/style.css

Add the following at the end of the file:

/* the following will provide a margin to CKEditor's editing screen to make it not so tight against the left */
body {
  margin: 10px;
}

/* the following will provide a border around text defined as "Formatted" using CKEditor's "Formatted" icon */
pre {
  border: 1px solid green;
  margin: 10px;
  background-color: #f8f9fa;
  padding: 0.5em;
}

/* the following will format the table of contents inserted using CKEditor's Table of Contents icon */
.widget-toc{
  display: table;
  border: 1px solid green;
  background-color: #f8f9fa;
  padding: 1em;
  font-size: 90%;
}

/* all the following will be needed to set up CKEditor's Style icon before use */

/* the following when used in conjunction with "p" for paragraph will give paragraph hanging indentation */
.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;
}

/* the following when used in conjunction with "p" for paragraph will give paragraph indentation */ 
.indent1 { 
  margin-left: 40px;
}
.indent2 {
  margin-left: 80px;
}
.indent3 {
  margin-left: 120px;
}
.indent4 {
  margin-left: 160px;
}

/* the following will give hanging indentation to headings */
h2.hang {
  margin-left: 40px;
  text-indent: -40px;
}
h3.hang {
  margin-left: 40px;
  text-indent: -40px;
}
h4.hang {
  margin-left: 40px;
  text-indent: -40px;
}

Save and exit.

After re-defining "pre" as above, CKEditor's Formatted icon will give the following dropdown menu:

Add style buttons to CKEditor

(Separated as a section, 21 Dec 2021)

Log in the website as an administrator.

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

Move the Styles Icon down to a suitable position in the menu bar.

A blank dropdown text box will appear below the menu bar.

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.

 

Install Composer and Drush

(section added, 26 May 2019)

Drupal.org website describes various methods of installing Composer and Drush, generally referring to other websites for complicated steps which are difficult to follow.

The following simple steps do work.

Execute:

$ sudo apt install composer
$ cd /var/www/html/web
$ composer require drush/drush

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

Update Drupal 8 using Composer

(section added, 18 Jan 2019)

Go to the root directory of the website:

$ cd /var/www/html/web

Configure "composer.json", if not done before: 

$ gedit composer.json

Move the following from the "replace" section to the beginning of the "require" section, with "," added at the end:

"drupal/core": "^8.7",

(configuration action added, 7 July 2019)

Update with the existing "core/composer.json":

$ cd core
$ composer update --with-dependencies
$ cd ..

Do similar update in case the following message is encountered when updating the "drupal/core" as described later below:

Dependency "..." is also a root requirement, but is not explicitly whitelisted. Ignoring.

(configuration action added, 18 July 2019)

(no longer necessary, 5 January 2020)

Check for outdated modules:

$ composer outdated drupal/*
$ composer show --outdated drupal/* -vvv

(syntax changed, 5 January 2020)

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

("-vvv" added to all commands, 5 January 2020)

Update all:

$ composer update drupal/core --with-dependencies
$ composer update drupal ---vvv

(simplified command appears also working, 5 January 2020)

Update database:

$ vendor/drush/drush/drush updatedb -vvv

 

("vendor/drush/drush/" added, 26 May 2019)

Clear cache:

$ vendor/drush/drush/drush cr -vvv

Log out the server.

Upgrade Drupal 8 to Drupal 9

(section added, 20 Sep 2020)

Not all modules and themes for Drupal 8 are compatible with Drupal 9. They should be checked for compatibility.

Go to the root directory of the website:

$ cd /var/www/html/web

Install the following extensions:

$ composer require drupal/upgrade_rector drupal/upgrade_status

Choose Admin > Manage > Report > Upgrade Status.

Select projects (modules and themes) and run to check compatibility.

Apply patches as suggested.

If all the modules and themes have been made compatible, do upgrading.

Upgrading procedures have been suggested at https://www.drupal.org/docs/upgrading-drupal/upgrading-from-drupal-8-to-drupal-9-or-higher. However, the following suggested commands did not work because of dependencies errors caused by incompatibility:

$ cd /var/www/html/web
$ composer require drupal/core-recommended:^9.0.6 drupal/core-composer-scaffold:^9.0.6 drupal/core-project-message:^9.0.6 --no-update
$ composer update

The following command did work:

$ cd /var/www/html/web
$ composer require "drupal/core:9.0.6 as 8.9.6" --no-update && composer update

"9.0.6" and "8.9.6" are the current Drupal 9 version and installed Drupal 8 version respectively at the time of writing this.

Update database:

$ vendor/drush/drush/drush updatedb -vvv

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

Error has been reported for the Mayo theme because the base theme has to be stated for Drupal 9.

Edit:

$ sudo nano themes/mayo/mayo.info.yml

Insert "base theme: stable" after the third line for "description".
Clear cache:

$ vendor/drush/drush/drush cr -vvv

Log out the server.

The Admin > Manage > Report > Upgrade Status page may still report incompatibility but this should not matter anymore.

Update Drupal 9 using Composer

(section added, 20 Sep 2020)

Same as those for Drupal 8:

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

Log out the server.

Update Drupal 9 core manually

(tested with 9.2.8, one error corrected, 11 November 2021)

(updated, 5 January 2020)

(section added, 26 May 2019)

Set the website to maintenance mode.

Backup the existing directories and files to another location, e.g. .../webold:

$ cd /var/www/html
$ sudo mv web webold
$ sudo cp -Ra web webold

Download the latest Drupal version, and extract the files as described for fresh installation, i.e.:

$ sudo wget https://ftp.drupal.org/files/projects/drupal-9.x.x.tar.gz 
(change "9.x.x" to the version number)
$ tar -xzf drupal-9.x.x.tar.gz         
("sudo" not used so that user instead of "root" will become owner)
$ mv drupal-9.x.x web

Change to website root directory, remove two sub-directories and all files in the top level directory, including hidden files:

$ cd /var/www/html/web/
$ rm -rf core vendor
$ rm -f *.* .[a-z]*

Change to downloaded directory, copy updated sub-directories and files to the existing website directories:

$ cd ../drupal-9.x.x
$ cp -R core vendor ../web
$ cp *.* .[a-z]* ../web

Update with Composer and Drush

$ composer update -vvv
$ composer require drush/drush
$ vendor/drush/drush/drush updatedb -vvv
$ 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.

In case of a need to re-use and copy some of the old user-defined directories and files to the new directories (keeping original attributes), do some of the following as appropriate:

$ cd /var/www/html
$ sudo cp -Rav webold/libraries web
$ sudo cp -Rav webold/modules web
$ sudo cp -Rav webold/profiles web
$ sudo cp -Rav webold/sites web
$ sudo cp -Rav webold/themes web
$ sudo cp -Rav webold/vendor web   
$ sudo cp -Rav webold/composer.json web   
$ sudo cp -Rav webold/composer.lock web 
$ sudo cp -Rav webold/misc web            (this one is not a standard directory)

 

Relocate or restore Drupal 8

(section added, 8 May 2019)

(revised, 16 May 2019)

Export the relevant MySQL database using phpMyAdmin as a backup.

Backup the whole Drupal directories and files. For example, if Drupal's root directory is /web in /var/www/html/web, then everything from and below /web.

Use old pair of backups if fresh pair not available.

Create a new user and blank database only if new computer or new MySQL-server is used. 

Import the database backup.

Move the whole Drupal directories and files to the new directory, e.g. /var/www/new/web.

Keep "new" as the original name in case of no change, e.g. /var/www/html/web.

Keep the name "/web" unchanged since this is hard-coded in the beginning of links  in the form of "/web/..." to media and files embedded in the web pages.

Execute

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

For

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

change the <text> to match the new database.

Change the DocumentRoot in the new site's currently used Apache2 site configuration file, e.g. /etc/apache2/sites-enabled/000-default.conf,  from "/var/www/html/" to /var/www/new, still one level above /web. Links in the form of "/web/..." to media and files will be interpreted as "/var/www/new/web/...", still accessible.

Web browsing to http://kctang.com.hk/web should be able to access Drupal at the new location.

Go to the next section in case web browsing fails to display.

If the DocumentRoot is set directly to the Drupal root directory "/var/www/new/web, web browsing of Drupal web pages is still possible, but links to media and files will be interpreted as "/var/www/new/web/web/... ", and the media and files will not be displayed.

Move the ".htaccess" file from /var/www/html to /var/www/new to re-direct web browsing to http://kctang.com.hk/web:

$ sudo mv /var/www/html/.htaccess /var/www/new

Execute as necessary:

$ vendor/drush/drush/drush updatedb -vvv
$ vendor/drush/drush/drush cr -vvv

("vendor/drush/drush/" added, 26 May 2019)

Use new shell to relocate and restore

(section added, 16 May 2019)

(revised, 26 May 2019)

If the relocation or restoration is not successful, non-display may happen because of some corruptions in the file settings.

Follow the Drupal core manual installation steps described above, but substitute "/var/www/html" described there with "/var/www/new".

Setting the website to maintenance mode would not be possible.

Before changing the settings file, move the ".htaccess" file from /var/www/html to /var/www/new:

$ sudo mv /var/www/html/.htaccess /var/www/new

Delete left-over module configuration files

(section added, 26 May 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>'

 

End of Page