Install Drupal 8 content management system

Go to End

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.

Note

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

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

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:

$ sudo 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:

$ sudo mkdir sites/default/files

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/7.2/apache2/php.ini

("7.0" changed to "7.2", 23 Sep 2018)

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/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/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". Select "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>

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:

$ gksudo 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 may be changed when there is an update 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

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

Log in the website as an administrator.

Select 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 core 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)

Check for outdated modules:

$ composer outdated drupal/*

Continue as follows if there is drupal/core to update:

$ composer update drupal/core --with-dependencies

Update database:

$ vendor/drush/drush/drush updatedb

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

Clear cache:

$ vendor/drush/drush/drush cr

Log out the server.

Update Drupal 8 core manually

(section added, 26 May 2019)

Set the website to maintenance mode.

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

$ sudo mv /var/www/html/web /var/www/html/webold

Download the latest Drupal version, extract and install the files to the intended location "/var/www/html" as described for fresh installation, i.e.:

$ sudo 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

(codes repeated to ease reading, 7 July 2019)

Copy the old user-defined directories and files to the new directories (keeping original attributes):

$ 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/misc web            (this one is not a standard directory)

New files in the root directory used.

("Rnv" changed to "Rav" to keep all existing files and attributes, 7 July 2019)

Edit the settings file:

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

("new" corrected as "html", 7 July 2019)

Change "FALSE" to "TRUE" in the following line:

$settings['update_free_access'] = FALSE;

Save file and exit.

Browse web to http://kctang.com.hk/web/update.php hopefully to see the opportunity to update the database, and update.

Execute as necessary if drush already installed, otherwise install composer and drush first:

$ vendor/drush/drush/drush updatedb
$ vendor/drush/drush/drush cr

Change "TRUE" back to "FALSE" in the settings file.

Set to release the website from maintenance mode.

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
$ vendor/drush/drush/drush cr

("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, 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