Install Custom Modules

In the event that the modules provided via the CERN Drupal Distribution) are not sufficient for your needs, you may:

• post on the CERN Drupal Community Forums to see whether others have already achieved what you are looking for;
• submit a request to the Drupal Team to evaluate whether the feature(s) you require can be accommodated by adding a new module to the CERN Drupal Distribution, benefitting all CERN websites; or
• manually install a custom module directly on your website(s).

danger

Please note that installing and using custom modules requires both (a) continuous maintenance and (b) continuous attention to updates, security patches, and new feature releases. Indeed, any website is a living and breathing piece of software. This work will solely be the responsibility of the website owner(s) as any custom module not in the CERN Drupal Distribution will not benefit from the centrally managed updates. If you require a set-and-forget solution, please do not exceed what is offered in the CERN Drupal Distribution.

Installing Modules

In order to install a custom module on a website, it is first and foremost a requirement that you have the appropriate permissions. Typically, this means being a member of the associate e-group. If you do not have administrative rights on the website in question, please get in touch with the website owner(s) before proceeding.

Installing Modules via Composer

Kindly note that while extensive, this is the recommended workflow for installing custom modules. The reason for this is that the actual installation as well as subsequent management and maintenance is significantly easier and largely automated. Indeed, composer install libraries and dependencies automatically by pasting a single line.

info

Installing modules using composer requires access to oc.

Please see this guide for how to connect to your website using oc.

info

The following steps require an understanding of how git works. If you are wholly unfamiliar with git, Gitlab, and repositories, please either refer to this guide, or skip to the WebDAV section. If you have any questions about the below steps, please create a thread on the CERN Drupal Community Forums.

1. Start by creating a new Gitlab repository with composer.json.

Forking the `drupalsite-extraconfig-template` repository.

Click Fork on the dedicated drupalsite-extraconfig-template repository to have a template to start from. Please ensure that you create your new repository in an appropriate location such that yourself and anyone who needs to access can do so. We do not recommend tying the repository to your personal CERN/Gitlab account.

Forking the `drupalsite-extraconfig-template` repository.

2. Once the repository has been created, you are ready to proceed.

In order to install a custom module, it must be included as a composer dependency. As an example, we will install the Better Exposed Filters module (https://www.drupal.org/project/better_exposed_filters). This can be achieved by editing the composer.json file.

You must select a specific release of the module you wish to install. Proceeding with Better Exposed Filters, we select version 6.0.1 (i.e. https://www.drupal.org/project/better_exposed_filters/releases/6.0.1) and copy the composer require statement.

Copying the `composer require` statement.

3. We proceed via Gitlab by clicking the composer.json file in our new repository.

Editing the `composer.json` file directly.

Next, we create a new line using the composer require statement we copied in step 2.

Editing the `composer.json` file directly.

In the above case, as no other module has been added, we merely edit line 11 to say "drupal/better_exposed_filters": "^6.0",. Remember the , at the end to ensure the file remains valid JSON. Once done, click Commit changes.

Editing the `composer.json` file directly.

Using Private Repositories

For security and / or privacy concerns, you may wish to use a private Gitlab repository. In order to do this, you need to create an Access Token on your Gitlab repository. Use the following steps to generate an Access Token. Remember to modify the Extra configs repo URL, too.

In the ‘Project Access Tokens’ page, complete the following fields

• Token name: Provide a custom name here, which will be used to refer to the token usage. The name is not very important and can be something simple like drupal
• Expiration date: This can be left empty, for the token to never expire. Or you can set a custom date. Note that, if you set a custom date, the workflow might not work post the specific date
• Select a role: Select the reporter role from the dropdown list
• Select scopes: In the scopes, make sure to only select read_repository checkbox

Click on the Create project access token button at the bottom. This will refresh the page and display an Access token at the top of the page. Make sure to copy and save this somewhere, as it is displayed only once. If you lose the token, repeat the steps again to create a new one

Fill the Extra configs field

If you have a public repository, you can provide your Gitlab URL in the Extra configs repo field. However, if you have a repository that is not public, in the Extra configs repo field, add username:accesstoken after https:// and before gitlab.cern.ch, e.g. https://<yourAccountName>:x-CjgFJxkxxDTuctAm8jG@gitlab.cern.ch/ravineet/test-ravineet-d9-containers-buildconfig.git.

Add Webhook Triggers

In order for changes committed to your Gitlab repository to be reflected on the website, i.e. for new builds to be created, this step is important. From your site management page, on the website you just created, find the Webhook URL listed and copy it. The URL can be found under the Advanced-tab of the environment in the Webservice Portal. If you do not see an URL, you must ensure that you have the appropriate permissions and submit a ticket.

On your Gitlab repositry, go to Settings > Webhooks. You will find these in the navigation bar on the left. Paste the URL you copied in the URL field and make sure only Push Events is checked in the Trigger section. Also uncheck the Enable SSL verification in the SSL verification section. Click on Add webhook image. With this setup, every time you push a commit to your repository, a new build will be built and deployed to your website.

Installing Modules via WebDAV

For users wanting to add local modules without going through the technical option(composer) can use the following steps to add modules/ themes through “webdav”:

1. Download the modules you wish to add locally on your machine
2. Access webdav following these steps
3. Copy the modules you downloaded to add in the modules directory
4. Login to the drupalsite as an admin and navigate to extend which should take you to <your-site-url>/admin/modules.
5. Search for the module you added, check the box for the corresponding line, scroll to the bottom & click on install
6. The drupal site should now have the newly added modules installed

Updating Modules

There are two ways in which modules can be updated, via (1) WebDAV, or (2) via oc. In any case, the process of updating a module must be completed by the website owner(s) directly. It is strongly recommended to always create a clone before attempting to update a module. If all goes well on the clone, steps should be repeated on your production website.

Updating Modules via WebDAV

note

We recommend experienced users to use oc and the composer directly.

If you are unsure how to connect to your website's WebDAV, please refer to this guide.

The below screenshot shows an example of a mounted WebDAV folder. All CERN websites share this structure.

A mounted WebDAV folder of a CERN website.

Navigate to the modules folder.

This folder contains all the modules currently installed on your website.

Kindly note that the names of the folders correspond to the machine names of the modules. Do not change these.

The modules folder of a CERN website.

At this stage, we need a local copy of the module we wish to update. There are several ways in which this can be obtained; this guide will the two most common: The Extend tab and the Upgrade Status report. If you already happen to have a local copy of the module you wish to update, kindly skip the next two sections.

---

Using the Extend Tab

1. Go through the Extend tab and select Update. On this page, all modules with new(er) releases are listed.

The Update tab under Extend.

2. Click the Release notes link. In this case, we proceed with the config_filter module.

This opens a new tab or window in which the specific release can be downloaded directly. Choose the .zip version.

Downloading a copy of a module.

Using the Upgrade Status Report

Another way of obtaining the most recent release of a specific module is to use the Upgrade Status report:

1. Access this by heading to Report and selecting the Upgrade Status report at the bottom.

The Reports tab.

2. Scroll to the Update section to identify modules in need of update(s).

In this case, we only have the quick_node_clone module marked as in need of an update.

Click on the Drupal.org version number.

Selecting a specific module.

This opens a new tab or window in which the specific release can be downloaded directly. Choose the .zip version.

Downloading a copy of a module.

---

At this stage, we have a copy of the module saved directly on our machine as a .zip file. Unzip the module.

Open the WebDAV window once again and drag-n-drop the folder into the modules folder in your WebDAV window.

Note how in the screenshot below, we are dragging the unzipped folder.

Dragging the unzipped module onto your server.

This will prompt a window asking you to confirm the overwrite. Select Continue.

Overwriting the old copy of the module.

Once the transfer has finished, the module in question has been updated accordingly.

If you are updating modules through the Upgrade Status report, re-scan the module(s) you have updated to verify the update.

Repeat this process for each module in need of an update.

Updating Modules via oc

0. Identify the module you wish to update, e.g. Better Exposed Filters, and find its project page on https://drupal.org/.

In this case, the module is hosted on https://www.drupal.org/project/better_exposed_filters/.

The Better Exposed Filters module.

Scroll to the bottom of the page and find the release you require. Click it.

The Better Exposed Filters module release 8.x-5.2.

1. Copy the composer installation command.

The Better Exposed Filters module release 8.x-5.2.

2. Connect to the pod serving your website.

If you are not sure how to do this, please refer to this guide.

3. Paste the installation command you copied in step 1. Hit enter.

4. Type yes and hit enter in order to update (and install and enable any necessary dependencies).

5. Wait for the installation to finish. This may take anywhere from a couple of seconds to a couple of minutes. Do not close the window.

6. In order to avoid any caching issues, write drush cr and hit enter.

7. Confirm that the module has been updated via the Drupal UI.

Your module is now updated.

Uninstalling Modules

While it is possible to also use oc to remove modules, it is typically easier to go through the Drupal interface directly. This approach has the added benefit of displaying warnings in the event that published content will be impacted by the removal of the module(s) in question.

note

If you wish to proceed with oc regardless, uninstalling and removing a module is done by typing composer remove <module_name>. We recommend also executing drush updb to ensure the database does not contain any module configurations that are no longer necessary. Complete the process by typing drush cr.

1. Go to the Extend tab and click Uninstall.

The Extend tab.

The Uninstall section under the Extend tab.

2. Search or scroll through the list for the module(s) you wish to uninstall and remove.

Tick the module(s) and scroll to the bottom, click Uninstall.

3. Confirm that the chosen module(s) will be uninstalled.

Confirm the removal of the chosen module(s).

Click Uninstall.

4. Confirm that the module(s) have been removed.

Confirming the uninstallation and removal of the chosen module(s).