NES for IOMAD Installation Guide

Learn how to install NES for IOMAD by direct download over an existing IOMAD 4.3 site.

Installation Method

NES for IOMAD is distributed as a downloadable archive that you extract over your existing IOMAD 4.3 site. Direct download is the only supported installation method.

If direct download does not fit your deployment process, please contact support@herodevs.com so we can advise.

ALWAYS back up your site - dirroot or IOMAD webroot, moodledata, and your database

before installing NES for IOMAD.

ALWAYS test NES for IOMAD on a local or development environment before pushing to production.

NES for IOMAD keeps $branch = '403', so anything that ran on IOMAD 4.3.3 remains compatible. See Verifying an NES for IOMAD Installation once you are done.

Run every IOMAD CLI script in this guide as your web server user - www-data on Debian and Ubuntu, apache on RHEL, Rocky, and AlmaLinux. Run as root they leave root-owned files in moodledata, and the site then fails with permission errors under the web server user.

Confirm your platform

Check your PHP and database versions against the Supported Platforms matrix.

Confirm your current IOMAD version

NES for IOMAD is a drop-in replacement for IOMAD 4.3.3, and your site must already be running exactly that version. If you are on an earlier 4.3.x release, upgrade to 4.3.3 through your normal IOMAD upgrade process first.

Installing over an earlier 4.3.x release is not supported. The extract commands below overwrite and add files but never delete, so every core file removed between your version and 4.3.3 would be left behind on disk.

From the admin interface: go to Site administration → Notifications. The version is shown at the bottom of the page.

From the command line:

sudo -u www-data php admin/cli/cfg.php --name=release

Enable maintenance mode

From the admin interface: go to Site administration → Server → Maintenance mode and set Maintenance mode to Enable.

From the command line:

sudo -u www-data php admin/cli/maintenance.php --enable

Pause scheduled tasks

Maintenance mode blocks web traffic but does not stop a system cron job from invoking admin/cli/cron.php. Stop or disable your cron runner before extracting, and re-enable it once the database update has finished.

Back up

Back up your dirroot or IOMAD webroot, your moodledata directory, and your database.

Disable the built-in update checks

IOMAD inherits Moodle's built-in update check, which queries download.moodle.org and does not know about NES for IOMAD releases. Left enabled, it reports your site as out of date and can offer to deploy upstream IOMAD over your NES files - including from the Notifications page you use later in this guide. Set both of these in config.php before you continue:

$CFG->disableupdatenotifications = true;
$CFG->disableupdateautodeploy = true;

Download and Install

Download the archive

CLI

Download the archive using your NES Access Token as the bearer token. Replace the version with the latest from the release notes:

NES_ACCESS_TOKEN=<your-access-token-beginning-with-"pat-">
curl --header "Authorization: Bearer $NES_ACCESS_TOKEN" --output ~/release.zip \
--location https://registry.nes.herodevs.com/composer/pkg/neverendingsupport/iomad/4.3.5+4.3.3:iomad/release.zip

Browser

Go to the URL for the current release which should be the following, but with the most recent version: https://registry.nes.herodevs.com/composer/pkg/neverendingsupport/iomad/4.3.5+4.3.3:iomad/release.zip

You will be prompted to enter a username and password. Use the email address associated with your NES subscription for the username and your PAT (personal access token) as the password. The file will download to your chosen location.

Download to a directory outside your webroot - the command above uses your home directory. An archive saved inside dirroot is served at a guessable URL, so anyone could download your NES release until you delete it.

Please contact support@herodevs.com if you don't have your access token.

You can also download through your browser using Basic Authentication. See Direct Downloads for instructions.

Extract over your existing site

Be sure to back up your codebase before running the following command.

Linux/macOS

Windows

unzip -o ~/release.zip -d /path/to/iomad

When in doubt, use the full path to your IOMAD installation.

The unzip -o and tar -xf commands overwrite existing files and add new ones from the archive. They do not remove files that are not in the archive. Always back up your codebase before making changes.

Your own files are left alone. The archive carries IOMAD core plus every component IOMAD ships with - the local/iomad*, local/email*, and local/report_* plugins, the iomad_* blocks, the iomadoidc and iomadsaml2 auth plugins, and the iomad, iomadboost, and iomadbootstrap themes - so their files are replaced by the copies in the release. Contributed plugins you installed yourself, your own custom themes, and your config.php are not touched. Changes you made inside IOMAD core or a bundled component are overwritten - reapply them afterwards.

Extract as a user that can write to dirroot. If you extracted as root, reset ownership to your web server user before continuing:

sudo chown -R www-data:www-data /path/to/iomad

The archive has no top-level folder - its contents are the site root. After extracting, version.php, config-dist.php, and the admin/, local/, and mod/ directories sit directly in dirroot. If you end up with /path/to/iomad/iomad/ instead, the archive landed one level too deep - move its contents up before continuing, or the site will report no pending update and keep running the old code.

Apply the database update

Serving the site from more than one node? Extract the archive on every node before running the database update, then run the update once. Nodes still holding the old code while the database is upgraded will behave inconsistently.

Set $CFG->upgradekey? The browser-based update prompts for it. Either have the key to hand, or use the command line, which does not ask for it.

The following is potentially destructive. Be sure to back up your database before running the following commands.

The release updates both IOMAD core and the bundled local_iomad plugin, so the database update covers each of them.

From the admin interface: log in as an administrator and go to Site administration → Notifications. IOMAD detects the new version on disk and starts the update process - review the version and environment pages, then confirm to apply the database update. Afterwards, purge caches from Site administration → Development → Purge caches.

From the command line:

sudo -u www-data php admin/cli/upgrade.php
sudo -u www-data php admin/cli/purge_caches.php

Disable maintenance mode

From the admin interface: go to Site administration → Server → Maintenance mode and set Maintenance mode to Disable.

From the command line:

sudo -u www-data php admin/cli/maintenance.php --disable

Verify your site works as expected, re-enable your cron runner, then delete the downloaded archive at ~/release.zip.

Rolling Back

If the upgrade fails, or the site does not come back healthy, restore the backups you took in Before You Begin. Restore the codebase and the database together: admin/cli/upgrade.php writes schema changes, so a restored database will not match NES code on disk, and restored code will not match an upgraded database.

Re-enable maintenance mode

sudo -u www-data php admin/cli/maintenance.php --enable

Restore the codebase

Replace dirroot with your pre-install backup. Do not extract the NES archive again.

Restore the database

Restore the database dump you took before the install, into the database your config.php points at.

Purge caches and bring the site back

sudo -u www-data php admin/cli/purge_caches.php
sudo -u www-data php admin/cli/maintenance.php --disable

Your moodledata directory does not normally need to be restored - purging caches is enough. If you do restore an older moodledata, make sure it matches the database you restored.

Tell us what went wrong at support@herodevs.com and we will help you get the install through on the next attempt.

Next Steps

Confirm the install with Verifying an NES for IOMAD Installation.

Your site will still compare itself against download.moodle.org and consider itself out of date. That is expected. The settings you applied in Before You Begin stop IOMAD from acting on it.

Every NES release ships a new $version. To apply a later release, repeat Before You Begin and Download and Install with the new archive, including the database update. IOMAD does not record the new version until the update runs.

The release notes are updated with every NES for IOMAD release, and HeroDevs emails customers a monthly release summary. If you are not receiving it, contact support@herodevs.com.