Moodle

License: GPLv3

This guide is tested with Moodle 5.2.2+ on Uberspace 8.0.91. We can't guarantee it to work with newer versions.

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:

• PHP
• MariaDB
• Cron
• Domains

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 php version list

Set PHP to version 8.4:

[isabell@moondust ~]$ uberspace tool php version set 8.4
OK: Set version of php to 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/$USER/moodledata

Warning

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

Installation

Download

Change into the directory containing your standard html document root. This guide assumes that html is empty:

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

Download the current Moodle 5.2 stable archive from the Moodle download page. The stable502 archive tracks the latest weekly build of Moodle 5.2:

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

Extract Moodle next to the document root:

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

This puts Moodle's files directly into /var/www/virtual/$USER/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/$USER/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/$USER/html

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

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

Check that the symbolic link points to the correct directory:

[isabell@moondust isabell]$ readlink -f /var/www/virtual/$USER/html
/var/www/virtual/$USER/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/$USER/.config/php
[isabell@moondust ~]$ nano /home/$USER/.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 https://isabell.uber.space/ in a browser of your choice.

Follow the installer:

1. Choose your language and continue.
2. Confirm the Moodle installation path.
3. For the data directory, enter /home/isabell/moodledata.
4. For the database driver, choose MariaDB (native/mariadb).
5. 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:

MAILTO=""
* * * * * /usr/bin/php /var/www/virtual/$USER/moodle/admin/cli/cron.php >/dev/null

This runs Moodle's cron script every minute, as recommended by Moodle.

Check your crontab:

[isabell@moondust ~]$ crontab -l
MAILTO=""
* * * * * /usr/bin/php /var/www/virtual/$USER/moodle/admin/cli/cron.php >/dev/null

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

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

Tuning

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.

Slash arguments worked without additional configuration on the tested Asteroid. If Moodle reports routing problems, you can enable its routing engine with local Apache directives.

Create or edit .htaccess inside the served public directory via the html symlink:

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

Add the following directives:

AcceptPathInfo On
FallbackResource /r.php

After changing .htaccess, purge Moodle's caches:

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

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/$USER/moodle/admin/cli/purge_caches.php

Debugging

Check whether Moodle responds:

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

Check the login page:

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

Check PHP errors:

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

Check the PHP service journal:

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

Updates

Note

Subscribe to the Moodle Git tags feed or 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/$USER/backups
[isabell@moondust ~]$ BACKUP_TIMESTAMP=$(date +%Y%m%d-%H%M%S)
[isabell@moondust ~]$ mariadb-dump --result-file=/home/$USER/backups/moodle-$BACKUP_TIMESTAMP.sql ${USER}_moodle
[isabell@moondust ~]$ gzip /home/$USER/backups/moodle-$BACKUP_TIMESTAMP.sql
[isabell@moondust ~]$ tar --create --gzip --file=/home/$USER/backups/moodle-files-$BACKUP_TIMESTAMP.tar.gz --directory=/ var/www/virtual/$USER home/$USER/moodledata

Read Moodle's official upgrading instructions and the release-specific upgrading notes before replacing the application code. The following example updates the Moodle 5.2 branch. Adjust the archive URL when upgrading to another branch.

Download and extract the new release next to the current installation:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/
[isabell@moondust isabell]$ wget --output-document=moodle-new.tgz https://packaging.moodle.org/stable502/moodle-latest-502.tgz
[isabell@moondust isabell]$ mkdir moodle-new
[isabell@moondust isabell]$ tar --extract --gzip --file=moodle-new.tgz --directory=moodle-new --strip-components=1
[isabell@moondust isabell]$ cp moodle/config.php moodle-new/config.php

Reinstall any additional plugins and themes in moodle-new as described in Moodle's upgrading instructions. Do not copy the old application directory over the new release.

Enable maintenance mode and replace the application directory:

[isabell@moondust isabell]$ php moodle/admin/cli/maintenance.php --enable
[isabell@moondust isabell]$ mv moodle moodle-old
[isabell@moondust isabell]$ mv moodle-new moodle

The existing html symlink now points to the new release. Run Moodle's upgrade script and purge its caches:

[isabell@moondust isabell]$ php moodle/admin/cli/upgrade.php --non-interactive
[isabell@moondust isabell]$ php moodle/admin/cli/purge_caches.php
[isabell@moondust isabell]$ php moodle/admin/cli/maintenance.php --disable

Check the site before removing moodle-old and moodle-new.tgz. The old application directory provides a rollback copy if the upgrade fails. Once the updated site works, remove both:

[isabell@moondust isabell]$ rm --recursive moodle-old
[isabell@moondust isabell]$ rm moodle-new.tgz

Further Reading

• Moodle documentation and release notes
• Moodle plugins directory — some plugins may require additional installation instructions or PHP extensions
• Moosh command-line tool — check that the version you install is compatible with your Moodle version