feat: install additional plugins from Git repos

README.md

@@ -4,13 +4,16 @@
 
 Deploys, installs, and upgrades [Moodle](https://moodle.org) on [Ubuntu](https://ubuntu.com) servers.
 
+Additionally, extends Moodle by installing plugins from Git.
+
 ## Requirements
 
 > Any pre-requisites that may not be covered by Ansible itself or the role
 > should be mentioned here. For instance, if the role uses the EC2 module, it may
 > be a good idea to mention in this section that the boto package is required.
 
-The role is only tested on long-term support versions of Ubuntu that still receive standard support.
+The role is only tested on long-term support versions of Ubuntu that still
+receive standard support.
 
 At the moment, the role only uses Apache web server which it installs itself.
 
@@ -25,13 +28,20 @@ At the moment, the role only uses Apache web server which it installs itself.
 ### Deployment of Source Code
 
 ```yaml
-moodle_deploy_repository: https://github.com/moodle/moodle  # Public repository.
-moodle_deploy_version: MOODLE_402_STABLE                    # Branch, tag, or commit.
-moodle_deploy_update: yes                                   # Whether to pull new commits.
-moodle_deploy_destination: /var/www/html/moodle             # Also the web document root.
+moodle_deploy_repository: https://github.com/moodle/moodle # Public repository.
+moodle_deploy_version: MOODLE_403_STABLE # Branch, tag, or commit.
+moodle_deploy_update: yes # Whether to pull new commits.
+moodle_deploy_destination: /var/www/html/moodle # Also the web document root.
 ```
 
-The Moodle source code can only be deployed from a public repository and only over HTTPS. For stable versions of Moodle, the associated Git branch can be specified, e.g. for version 4.2, branch `MOODLE_402_STABlE` is used. Whenever the role is run and new commits are available on the specified branch, variable `moodle_deploy_update` specifies whether those new commits should be pulled down. If `yes`, the Moodle instance will also be updated. The directory to which the Moodle source code is deployed `moodle_deploy_destination` will also the directory from which the web server will serve it.
+The Moodle source code can only be deployed from a public repository and only
+over HTTPS. For stable versions of Moodle, the associated Git branch can be
+specified, e.g. for version 4.3, branch `MOODLE_403_STABlE` is used. Whenever
+the role is run and new commits are available on the specified branch, variable
+`moodle_deploy_update` specifies whether those new commits should be pulled
+down. If `yes`, the Moodle instance will also be updated. The directory to
+which the Moodle source code is deployed `moodle_deploy_destination` will also
+the directory from which the web server will serve it.
 
 ---
 
@@ -62,13 +72,13 @@ If a database service is installed, the specified user `moodle_cfg_dbuser` will
 ### Web Hosting
 
 ```yaml
-moodle_web_service: apache2           # Or nginx, but only apache is currently supported.
-moodle_web_root: subdirectory         # of existing virtualhost or root of new virtualhost.
+moodle_web_service: apache2 # Or nginx, but only apache is currently supported.
+moodle_web_root: subdirectory # of existing virtualhost or root of new virtualhost.
 moodle_web_protected_directories: ... # See defaults/main.yml for default list.
-moodle_web_protected_files: ...       # See defaults/main.yml for default list.
-moodle_web_protocol: http             # Whether Moodle is served over 'https' or just 'http'.
-moodle_web_domain: 127.0.0.1          # Domain name of the web service virtual host.
-moodle_web_path: moodle               # Subdirectory relative to virtual host.
+moodle_web_protected_files: ... # See defaults/main.yml for default list.
+moodle_web_protocol: http # Whether Moodle is served over 'https' or just 'http'.
+moodle_web_domain: 127.0.0.1 # Domain name of the web service virtual host.
+moodle_web_path: moodle # Subdirectory relative to virtual host.
 ```
 
 Variable `moodle_web_root` specifies whether Moodle is served from a subdirectory of an existing virtual host or whether a new virtual host must be created for it specifically. If `subdirectory` is specified, then `moodle_deploy_destination` and `moodle_web_path` must be in accordance with it.
@@ -79,7 +89,7 @@ Variable `moodle_web_root` specifies whether Moodle is served from a subdirector
 
 ```yaml
 moodle_environment: production
-moodle_cfg_wwwroot: ...  # Calculated based on web protocol, domain and path.
+moodle_cfg_wwwroot: ... # Calculated based on web protocol, domain and path.
 moodle_cfg_dataroot: ... # Calculated based on web domain and path.
 moodle_site_fullname: Modular Object-Orientated Dynamic Learning Environment
 moodle_site_shortname: Moodle
@@ -93,6 +103,25 @@ moodle_admin_email: moodler@never.stops.learning
 moodle_support_email: "{{ moodle_admin_email }}"
 ```
 
+---
+
+### Plugins
+
+```yaml
+moodle_plugins_git: []
+```
+
+A list of plugins that must be installed from a Git repository, because they
+are not available in the official plugins directory. For each plugin, the
+following must be specified:
+
+- frankenstyle name of the plugin, e.g. mod_questionnaire, block_xp.
+- URL to the repository;
+- the version reference (that is the branch, tag or commit).
+
+Additional plugins that are already installed, but that are not in this list,
+will be uninstalled.
+
 ## Dependencies
 
 > A list of other roles hosted on Galaxy should go here, plus any details in
@@ -106,11 +135,15 @@ The list of roles on which this role depends can be found in `requirements.yml`
 > Including an example of how to use your role (for instance, with variables
 > passed in as parameters) is always nice for users too:
 
-```ansible
+```yaml
 - hosts: servers
   roles:
     - role: geoffreyvanwyk.moodle
-      moodle_deploy_version: MOODLE_402_STABLE
+      moodle_deploy_version: MOODLE_403_STABLE
+      moodle_plugins_git:
+        - name: theme_learningsandboxonline
+          repository: https://github.com/geoffreyvanwyk/moodle-theme_learningsandboxonline
+          version: MOODLE_403_STABLE
 ```
 
 ## License

defaults/main.yml

@@ -24,7 +24,7 @@
 
 # Deployment of Source Code
 moodle_deploy_repository: https://github.com/moodle/moodle # Public repository.
-moodle_deploy_version: MOODLE_402_STABLE # Branch, tag, or commit.
+moodle_deploy_version: MOODLE_403_STABLE # Branch, tag, or commit.
 moodle_deploy_update: true # Whether to pull new commits.
 moodle_deploy_destination: /var/www/html/moodle # Also the web document root.
 
@@ -155,3 +155,7 @@ moodle_support_email: "{{ moodle_admin_email }}"
 ##   enabledashboard: 0
 ##   navcourselimit: 12
 moodle_cfg_forcedsettings: {}
+
+# Extend with Plugins
+
+moodle_plugins_git: []

molecule/plugins/converge.yml

@@ -0,0 +1,42 @@
+---
+# This file is part of Ansible role geoffreyvanwyk.moodle.
+#
+# Ansible role geoffreyvanwyk.moodle is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible role geoffreyvanwyk.moodle is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Ansible role geoffreyvanwyk.moodle. If not, see
+# <https://www.gnu.org/licenses/>.
+
+##
+# Contains the call to the role when testing with Molecule.
+#
+# @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
+##
+
+- name: Converge
+  hosts: all
+
+  vars_files:
+    - vars/main.yml
+
+  tasks:
+    - name: Update APT package cache
+      # Sometimes the package list on the server does not contain all the
+      # available packages. A fresh list has to be downloaded from the Ubuntu
+      # package repositories.
+      become: true
+      ansible.builtin.apt:
+        update_cache: true
+        cache_valid_time: "{{ 60 * 60 * 24 }}" # seconds => 24 hours
+
+    - name: "Include geoffreyvanwyk.moodle"
+      ansible.builtin.include_role:
+        name: "geoffreyvanwyk.moodle"

molecule/plugins/molecule.yml

@@ -0,0 +1,43 @@
+---
+# This file is part of Ansible role geoffreyvanwyk.moodle.
+#
+# Ansible role geoffreyvanwyk.moodle is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible role geoffreyvanwyk.moodle is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Ansible role geoffreyvanwyk.moodle. If not, see
+# <https://www.gnu.org/licenses/>.
+
+##
+#  The central configuration entrypoint for Molecule.
+#
+# @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
+# @link       http://tinyurl.com/molecule-scenario-layout
+##
+
+dependency:
+  name: galaxy
+driver:
+  name: docker
+platforms:
+  - name: ansible_role_moodle_molecule_${MOLECULE_DISTRO:-ubuntu2204}
+    image: "geoffreyvanwyk/docker-${MOLECULE_DISTRO:-ubuntu2204}-ansible:latest"
+    pre_build_image: true
+    published_ports:
+      - "0.0.0.0:80:80"
+provisioner:
+  name: ansible
+  inventory:
+    host_vars:
+      ansible_role_moodle_molecule_${MOLECULE_DISTRO:-ubuntu2204}:
+        ansible_user: ubuntu
+        moodle_deploy_version: ${MOLECULE_MOODLE_VERSION:-MOODLE_403_STABLE}
+verifier:
+  name: ansible

molecule/plugins/vars/main.yml

@@ -0,0 +1,28 @@
+---
+# This file is part of Ansible role geoffreyvanwyk.moodle.
+#
+# Ansible role geoffreyvanwyk.moodle is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible role geoffreyvanwyk.moodle is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Ansible role geoffreyvanwyk.moodle. If not, see
+# <https://www.gnu.org/licenses/>.
+
+##
+# Override variables for this Molecule scenario.
+#
+# @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
+##
+
+moodle_plugins_git:
+  - name: theme_learningsandboxonline
+    repository: >-
+      https://github.com/geoffreyvanwyk/moodle-theme_learningsandboxonline
+    version: "{{ moodle_deploy_version }}"

molecule/plugins/verify.yml

@@ -0,0 +1,51 @@
+---
+# This file is part of Ansible role geoffreyvanwyk.moodle.
+#
+# Ansible role geoffreyvanwyk.moodle is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible role geoffreyvanwyk.moodle is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Ansible role geoffreyvanwyk.moodle. If not, see
+# <https://www.gnu.org/licenses/>.
+
+##
+# Contains specific tests against the state of the container after the role has
+# finished executing.
+#
+# @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
+##
+
+- name: Verify
+  hosts: all
+  gather_facts: false
+
+  vars_files:
+    - ../../defaults/main.yml
+    - vars/main.yml
+
+  tasks:
+    - name: Obtain list of additional plugins
+      args:
+        executable: /bin/bash
+      ansible.builtin.shell:
+        chdir: "{{ moodle_deploy_destination }}"
+        cmd: >-
+          set -o pipefail
+          &&
+          php admin/cli/uninstall_plugins.php --show-contrib
+          |
+          cut -f1
+      register: moodle_additional_plugins_installed
+      changed_when: false
+
+    - name: Assert that plugins are installed
+      loop: "{{ moodle_plugins_git }}"
+      ansible.builtin.assert:
+        that: item.name in moodle_additional_plugins_installed.stdout_lines

requirements.yml

@@ -21,4 +21,8 @@
 # @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
 ##
 
-- name: geoffreyvanwyk.php
+roles:
+  - name: geoffreyvanwyk.php
+
+collections:
+  - name: geoffreyvanwyk.moodle

tasks/deploy_plugins.yml

@@ -0,0 +1,35 @@
+---
+# This file is part of Ansible role geoffreyvanwyk.moodle.
+#
+# Ansible role geoffreyvanwyk.moodle is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible role geoffreyvanwyk.moodle is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# Ansible role geoffreyvanwyk.moodle. If not, see
+# <https://www.gnu.org/licenses/>.
+
+##
+# Clone source code of plugins from remote Git repository hosts like GitHub.
+#
+# @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
+##
+
+- name: Deploy source code of plugins
+  loop: "{{ moodle_plugins_git }}"
+  ansible.builtin.git:
+    repo: "{{ item.repository }}"
+    version: "{{ item.version }}"
+    dest: "{{
+      moodle_deploy_destination + '/' +
+      lookup(
+      'geoffreyvanwyk.moodle.plugin_directory',
+      frankenstyle_name=item.name
+      )
+      }}"

tasks/deploy_source_code.yml

@@ -16,8 +16,8 @@
 # <https://www.gnu.org/licenses/>.
 
 ##
-# Deploy the Moodle source code from a remote source code repository host like
-# GitHub.
+# Deploy the Moodle and plugins source code from a remote source code
+# repository host like GitHub.
 #
 # @copyright  2023 Geoffrey Bernardo van Wyk (https://geoffreyvanwyk.dev)
 ##

tasks/main.yml

@@ -31,6 +31,9 @@
 - name: Deploy Moodle
   ansible.builtin.import_tasks: ./deploy_source_code.yml
 
+- name: Deploy Plugins
+  ansible.builtin.import_tasks: ./deploy_plugins.yml
+
 - name: Install and configure web hosting
   ansible.builtin.import_tasks: ./configure_web_hosting.yml