Common Moodle installation mistakes (and their solutions)
Moodle software is a mature, full-featured LMS that can perform quite well. When installed correctly, it runs right out of the box. However, when incorrectly installed, it can be a frustrating experience and you might be blaming Moodle. Here are some of the most common installation mistakes which may be affecting your Moodle site.
1. Required PHP extensions are not installed or are disabled
Moodle makes use of several required PHP extension libraries to work and perform properly. If the installer made the mistake of not enabling them or did not apply one or more of the recommended PHP settings, you might get the impression that Moodle is slow or broken.
It is quite common to overlook enabling PHP OPcache in php.ini on your web server is quite common because Moodle just gives you a warning but still allows you to proceed with the installation. However, enabling OPcache can significantly improve performance. You will be amazed by doing this alone. Task completions and page loads, that took minutes, are often reduced to seconds. It does make that much of a difference. If you don’t enable this one feature, you are just torturing yourself… and your teachers and learners.
Check the configuration of your server by navigating to Site administration > Server > Environment. For best results, ensure that every line in the Status column indicates OK. Fix everything that is not, even if it is just a warning. The error messages will be links that will take you to information on how to resolve the issue.
2. Cron is not set to run Moodle’s Task Scheduler every 1 minute
Cron is so important, this should be the first thing you correct after installing Moodle. Forgetting to configure cron is an installation mistake. Moodle needs the cron heartbeat by design.
Cron is the heartbeat of Moodle’s Task Scheduler which runs many functional and maintenance tasks at different intervals on even the smallest and simplest of Moodle sites. Without it, it may look like your site is running well, but you will eventually start to notice that things are getting slower or don’t work such as processing course completions, cloning courses, resetting passwords, sending out forum emails and much more. Eventually, users will be unable to even log in or Moodle will stop working completely. It may not happen today or even next month, but it will eventually catch up with you by which time you may not remember why. You can find a list of the tasks scheduled by navigating to Site Administration > Server > Task > Task Scheduler.
Running cron less often than the recommended once per minute will accumulate the tasks pending resulting in a heavier impact on your web and database servers, even if it is less frequent. This will be much more noticeable to your users.
You can check to see if cron is running by going to Site Administration > Notification. Configure cron to run every 1 minute to minimize the load and to keep your site feeling responsive and operational. Users will love you for it.
3. Incorrect file or directory permissions
Moodle needs to be able to create, read, write and delete files on your web server. I can’t begin to list all the things that can go wrong if your web server has insufficient file and directory permissions. This is a common installation mistake.
Administrators sometimes set the Moodle application file area to be read-only for security reasons or to prevent the installation of themes and plugins. This is quite common and there can be valid reasons for doing this. However, if this was not the intention, or your website just isn’t showing any indications of life, your web server likely has a file and directory permissions issue.
Moodle also needs to have full access to the moodledata folder. This workspace is used by Moodle for doing multiple purposes such as storing course files, caching files, storing additional/custom language strings and more. Moodle must have full control of that space.
Fixing this varies considerably from one system to another. The key is to ensure that the user or group under which your web server (e.g., Apache) is running has the appropriate permissions to read files. In the case of moodledata, it also needs to be able to create, write and delete files and directories.
File and directory permissions can be confusing to new inexperienced administrators until they realize that their web server is often running under a different user than they are. Something to keep in mind when you are manually copying files on your web server.
For more information on setting permissions, consult the documentation for your operating system.
4. Insufficient memory or disk space
Moodle is a resource-hungry application. Technically, Moodle’s minimum system requirement is 512 MB of memory. However, if you check the system requirements of each component that go into building a Moodle website (operating system, web server, PHP, database server and Moodle itself), you will likely discover that the minimum amount of memory required is often 2 or 4 GB – minimum. The more concurrent active users you have on your site, the more memory your servers will need.
Computers and servers do not see the humour in running out of memory or available disk space. When it happens, they will do nasty things like crash. On a really bad day, they may also corrupt files, the file system, and/or make a mess of your database. These machines do not care if your backup failed last night, if it is final exam time, or if you are having relationship or financial issues in your life.
What can you do about it? Keep them happy by doing all of the following:
- Always have a recent backup that is restorable, not just in theory. Test your restore process periodically.
- See #1 (in case you skipped over it). It may help you with your relationship and financial issues when things go wrong. Automate it and you may also sleep better at night.
- Set up a swap file. Its size should be 2-4 times the physical memory in the server.
Your two options are: having a more robust system that slows down when it runs out of memory or living with a more fragile system that will crash when it runs out of memory.Unless your instance of Moodle is running in a containerized environment, be responsible and just create the swap file. - Ensure that your servers have sufficient free memory. Some people may advise you that a swap file is unnecessary and will cause your SSD drive to deteriorate more quickly. This is true, however, with enough memory, the swap file may never be used, and your SSD won’t wear out any faster and your students will enjoy a better-performing Moodle site.
- Ensure that your servers have an ample supply of free space available. It does not take very long for someone to upload a video in a course and use up those precious last few gigabytes of disk space. Even if you never upload another file into your LMS, Moodle and your web server are constantly creating cached and data files, log files and making changes to the database behind the scenes.
5. Incorrectly upgraded
I am regularly surprised at how many Moodle sites are upgraded by some well-intentioned person by simply copying a new version of Moodle right over the old version. What a mess this can be to clean up. Even worse is if you skip over too many versions without going through the Moodle upgrade processes, the database ends up being a mess too. Upgrading Moodle can usually be a relatively easy and smooth process. Read Moodle’s online documentation on Upgrading and the Upgrading FAQ before attempting an upgrade. Otherwise, you may as well let your cat take a stab at upgrading your Moodle site. You’ll probably end up with similar results.
Don’t forget 3rd party plugins and themes. While many of them work just fine with multiple releases of Moodle, Moodle is constantly evolving and some may have specific releases of their plugins and themes for specific versions of Moodle. Make sure you have the right version installed and remember to also upgrade additional plugins and themes when you upgrade Moodle, especially when going from one major release to another.
But what if a compatible version of your plugin or theme is not yet available? Just because it is not listed as compatible on moodle.org/plugins does not necessarily mean that it is incompatible. While that is a possibility, it could also simply mean that the maintainer has not yet tested it. Read the comments to see if anyone else has already tried it. Bottom line, if it seems to work for you, it is likely just fine. I still use some old plugins from Moodle 3.2 which work just fine on Moodle 3.11.
Pro tip: Always perform upgrades on a copy of your Moodle site, such as a sandbox site or even on your personal computer first and test it thoroughly before attempting to install it on your live production site.
6. Varnish Cache is enabled
While I appreciate cloud hosting providers who try to simplify the Moodle site installation process for their customers, I have seen brand new sites that just won’t work at all and others that won’t let you log in right after the installation is completed. If you are having similar issues, check to see if Varnish Cache is enabled and, if it is, disable it. If it fixes your problem, you will know the cause and can either leave it off or figure out how to configure it to work.
7. Application/moodledata and the database on the same server
This one isn’t so much of an installation mistake as it is a performance and stability optimization technique. The Moodle software, web server and operating system all compete for CPU, memory and disk storage. This can affect the stability and performance of your Moodle site. There may not be much you can do about it if your site is hosted on your local computer or a shared hosting plan.
However, if you can, moving your database to a separate server frees each server (web and database) to have all the resources they need to perform well and reliably. It is like having 10 people and one apple pie. It is obviously better to slice 2 apple pies into 6 pieces each than to try and slice one pie into 12 pieces – especially if my wife made the pies.
- Moodle LMS Email Deliverability in 2024: Best Practices, Authentication Standards and Troubleshooting – 23rd February 2024
- Terminology for Those New to Moodle LMS – 20th January 2024
- Enhancing E-Learning in Moodle LMS with an AI Chat Block and FilterCodes – 20th November 2023
Great post 🙂
I’ve seen and read many discussions around the ‘correct’ size of swap to use … and I still never feel I have found the definitive answer, lol.
8. Installing or using contributed plugins not designed for the version of Moodle you are using.