Install Drupal 8 content management system

Note

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

(revised 23 Sep 2018, 3 Sep 2018)

Prepare

Install Apache2 web server if not already installed.

Enable Apache2 rewrite module:

$ 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 Drupal 8.x.x (filename drupal-8.x.x.tar.gz) from https://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" instead of the default of "drupal":

$ sudo mkdir /var/www/web

Change to that directory:

$ cd /var/www/web

Move the contents under drupal-8.x.x:

$ sudo mv /home/<own account name>/Downloads/drupal-8.x.x/* .

See if there are hidden files beginning with ".", e.g. ".htaccess", ".gitignore":

$ sudo ls -la /home/<own account name>/Downloads/drupal-8.x.x

Move the hidden files also, individually:

$ sudo mv /home/<own account name>/Downloads/drupal-8.x.x/<hidden file name> .

or all, which may give an error message:

$ sudo mv /home/<own account name>/Downloads/drupal-8.x.x/.* .

Check again for successful move:

$ sudo ls -la
$ sudo ls -la /home/<own account name>/Downloads/drupal-8.x.x

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/install.php, and follow the instructions there, using:

  • 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/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"

Create a new ".htaccess" file under "/var/www":

$ sudo gedit /var/www/.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/" 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/.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.

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/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);

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/web/libraries/<plugin directory name>

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