Guide moodle

{% include 'guide_header.md' %}

Moodle is a free and open-source learning management system written in PHP. It can be used to create courses, manage users, provide learning materials, run quizzes and assignments, and operate online learning platforms.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites¶

Moodle 5.2 requires PHP 8.3 or newer and MariaDB 10.11 or newer. This guide uses PHP 8.4.

Check the available PHP versions:

[isabell@moondust ~]$ uberspace tool version list php

Set PHP to version 8.4:

[isabell@moondust ~]$ uberspace tool version set php 8.4

Check the active PHP version:

[isabell@moondust ~]$ php --version
PHP 8.4.x (...)

You'll need your MariaDB credentials during the Moodle web installer. Get them with my_print_defaults:

[isabell@moondust ~]$ my_print_defaults client
--user=isabell
--password=MySuperSecretPassword

We will create a separate database for Moodle:

[isabell@moondust ~]$ mariadb -e "CREATE DATABASE ${USER}_moodle

Check that the database exists:

[isabell@moondust ~]$ mariadb -e "SHOW DATABASES"
+--------------------+
| Database           |
+--------------------+
| information_schema |
| isabell            |
| isabell_moodle     |
+--------------------+

Your URL needs to be set up:

[isabell@moondust ~]$ uberspace web domain list

  Domain           
 ───────────────── 
  isabell.uber.space

Data directory¶

Moodle saves uploaded files, cache data, temporary data and other persistent data into a separate data directory. This directory must not be reachable through the web server.

Create the data directory outside of the document root:

[isabell@moondust ~]$ mkdir /home/isabell/moodledata

Warning

Do not create the Moodle data directory inside /var/www/virtual/isabell/. The Moodle data directory must not be directly accessible from the web.

Installation¶

Download¶

Change into the standard document root of your Uberspace. This guide assumes that the document root is empty:

[isabell@moondust ~]$ cd /var/www/virtual/isabell/

Download the latest Moodle stable archive from the Moodle download page. The download link on the Moodle download page is a redirect, so use the direct tgz link, e.g. https://packaging.moodle.org/stable502/moodle-latest-502.tgz:

[isabell@moondust isabell]$ wget -O moodle.tgz https://packaging.moodle.org/stable502/moodle-latest-502.tgz

Extract Moodle into the document root:

[isabell@moondust isabell]$ tar --extract --gzip --file=moodle.tgz

This puts Moodle's files directly into /var/www/virtual/isabell/moodle/.

Remove the downloaded archive:

[isabell@moondust isabell]$ rm moodle.tgz

Moodle 5.1 and later ship with a dedicated public directory. The web server should only serve this public directory, while the rest of the Moodle application code should remain outside the document root.

In this guide, Moodle is installed into /var/www/virtual/isabell/moodle/, and the default html document root is replaced with a symbolic link to Moodle's public directory.

Remove the default html directory:

[isabell@moondust isabell]$ rmdir /var/www/virtual/isabell/html

Create a symbolic link from html to Moodle's public directory:

[isabell@moondust isabell]$ ln -s /var/www/virtual/isabell/moodle/public /var/www/virtual/isabell/html

Check that the symbolic link points to the correct directory:

[isabell@moondust isabell]$ readlink -f /var/www/virtual/isabell/html
/var/www/virtual/isabell/moodle/public

The Moodle installer will now be available at:

[isabell@moondust isabell]$ echo "https://isabell.uber.space/"
https://isabell.uber.space/

PHP configuration¶

Moodle requires max_input_vars to be set to 5000 or higher. Create a custom PHP configuration file:

[isabell@moondust ~]$ mkdir --parents /home/isabell/.config/php
[isabell@moondust ~]$ nano /home/isabell/.config/php/max_input_vars.ini

Add the following content:

max_input_vars = 5000

Reload PHP to activate the configuration:

[isabell@moondust ~]$ uberspace web php reload

Check the active value:

[isabell@moondust ~]$ php -i | grep max_input_vars
max_input_vars => 5000 => 5000

Setup¶

Now you should be able to access the Moodle web installer.

Open your Uberspace domain in a browser of your choice:

https://isabell.uber.space/

Follow the installer:

Choose your language and continue.
Confirm the Moodle installation path.
For the data directory, enter /home/isabell/moodledata.
For the database driver, choose MariaDB (native/mariadb).
Enter your database settings:

Database host: localhost
Database name: isabell_moodle
Database user: isabell
Database password: MySuperSecretPassword
Database port: 3306

Replace MySuperSecretPassword with the password shown by my_print_defaults client.

Continue through the installation checks, accept the license notice if you agree with it, create your administrator account and enter the full and short name of your Moodle site.

Configuration¶

Cronjob¶

Moodle needs its cron script to run regularly. The cron script is required for background tasks such as sending notifications, processing events and running scheduled jobs.

Open your crontab:

[isabell@moondust ~]$ crontab -e

Add the following lines:

PATH=/home/isabell/bin:/usr/bin:/bin
MAILTO=""
*/5 * * * * php /var/www/virtual/isabell/moodle/admin/cli/cron.php

This runs Moodle's cron script every five minutes.

Check your crontab:

[isabell@moondust ~]$ crontab -l
PATH=/home/isabell/bin:/usr/bin:/bin
MAILTO=""
*/5 * * * * php /var/www/virtual/isabell/admin/cli/cron.php

You can also run the cron script manually once to check its correct execution:

[isabell@moondust ~]$ php /var/www/virtual/isabell/admin/cli/cron.php

Best practices¶

Documentation¶

Moodle has extensive documentation. Check the official Moodle documentation and the release notes.

Routing, slash arguments and `.htaccess`¶

Moodle requires so-called slash arguments for some features. On Apache, Moodle documents AcceptPathInfo On as the relevant setting. Moodle also documents its routing engine and the use of FallbackResource /r.php for Apache-based setups.

On Uberspace, first follow the standard installation above. Only add local Apache directives if Moodle reports routing or slash argument problems, or if specific Moodle URLs do not resolve correctly.

If required, create or edit the .htaccess file in your Moodle document root:

[isabell@moondust ~]$ nano /var/www/virtual/isabell/.htaccess

Add the following directives:

AcceptPathInfo On
FallbackResource /r.php

After changing .htaccess, purge Moodle's caches:

[isabell@moondust ~]$ php /var/www/virtual/isabell/admin/cli/purge_caches.php

You can test how Moodle handles a non-existing route:

[isabell@moondust ~]$ curl -i https://isabell.uber.space/non-existing-moodle-router-test | head -40

For details, see the official Moodle documentation about Apache.

Caches¶

When you change configuration files or move installation paths, purge Moodle's caches:

[isabell@moondust ~]$ php /var/www/virtual/isabell/admin/cli/purge_caches.php

Moosh¶

Moosh exposes Moodle maintenance functions through a command line interface. It can be useful for lower-level administrative tasks. Always check that the Moosh version you install is compatible with your Moodle version.

Plugins¶

Moodle can be extended by plugins. Check out the Moodle plugins directory. Note that some plugins may require additional installation instructions or additional PHP extensions.

Updates¶

Note

Check the Moodle downloads page regularly to stay informed about new releases.

Before updating Moodle, create backups of the database and files:

[isabell@moondust ~]$ mkdir --parents /home/isabell/backups
[isabell@moondust ~]$ mariadb-dump isabell_moodle | gzip > /home/isabell/backups/moodle-$(date +%Y%m%d-%H%M%S).sql.gz
[isabell@moondust ~]$ tar --create --gzip --file=/home/isabell/backups/moodle-files-$(date +%Y%m%d-%H%M%S).tar.gz /var/www/virtual/isabell /home/isabell/moodledata

Read Moodle's official upgrading notes before replacing the application code.

After an update, run Moodle's upgrade script:

[isabell@moondust ~]$ php /var/www/virtual/isabell/admin/cli/upgrade.php

Then purge caches:

[isabell@moondust ~]$ php /var/www/virtual/isabell/admin/cli/purge_caches.php

Debugging¶

Check whether Moodle responds:

[isabell@moondust ~]$ curl -I https://isabell.uber.space/
HTTP/2 200

Check the login page:

[isabell@moondust ~]$ curl -I https://isabell.uber.space/login/index.php
HTTP/2 200

Check PHP errors:

[isabell@moondust ~]$ tail -f /home/isabell/logs/php_error.log

Check the PHP service journal:

[isabell@moondust ~]$ journalctl --user --unit php-fpm