Installation FAQ

Installation FAQ

This page addresses the most common questions and problems encountered when installing Moodle. If you encounter issues during installation, check this guide before seeking further help.

Common Installation Problems

Blank White Page After Installation

A blank white page (sometimes called the "white screen of death") typically indicates a PHP error that is not being displayed. To diagnose:

1. Check the web server error log (e.g., /var/log/apache2/error.log or /var/log/nginx/error.log)
2. Enable PHP error display temporarily by adding to the top of index.php:

   ini_set('display_errors', 1);
   error_reporting(E_ALL);
   

3. Check if config.php was created properly
4. Verify that all required PHP extensions are installed: php -m
5. Check the PHP memory limit — increase to at least 256M in php.ini

Database Connection Errors

If Moodle cannot connect to the database, verify the following:

• Database server is running: systemctl status mysql or systemctl status postgresql
• Database credentials in config.php are correct
• The database user has been granted the required privileges
• For MySQL/MariaDB, verify the character set is utf8mb4:

  SHOW CREATE DATABASE moodle;

• Check if the database host is correct (use localhost or 127.0.0.1 — they can behave differently with MySQL socket vs TCP connections)

File Permission Errors

"Could not create data directory" or "moodledata is not writable" errors:

• Ensure the moodledata directory exists and is writable by the web server user:

  sudo mkdir -p /var/moodledata
  sudo chown www-data:www-data /var/moodledata
  sudo chmod 750 /var/moodledata
  

• On SELinux-enabled systems, set the correct context:

  sudo chcon -R -t httpd_sys_rw_content_t /var/moodledata
  

• Check that the parent directory allows the web server to access the path

PHP Extension Missing Errors

Moodle checks for required PHP extensions during installation. If an extension is missing:

On Debian/Ubuntu:

sudo apt install php8.2-intl php8.2-xml php8.2-curl php8.2-zip php8.2-gd php8.2-mbstring php8.2-soap php8.2-sodium
sudo systemctl restart apache2

On RHEL/CentOS/AlmaLinux:

sudo dnf install php-intl php-xml php-curl php-zip php-gd php-mbstring php-soap php-sodium
sudo systemctl restart httpd

config.php Was Not Created

If the installer fails to create config.php, create it manually based on the template file config-dist.php:

cp config-dist.php config.php

Then edit config.php with your database and site details.

"Not enough memory" During Installation

Installation and upgrade processes require more memory than normal operation. Increase the PHP memory limit:

# In php.ini
memory_limit = 512M

# Or in config.php before the require line
ini_set('memory_limit', '512M');

Frequently Asked Questions

Can I install Moodle on shared hosting?

Yes, but with limitations. Your host must support PHP 8.1+, provide MySQL/MariaDB/PostgreSQL access, and allow cron jobs. Many shared hosts impose memory limits or restrict CLI access, which can cause problems. A VPS or dedicated server is recommended for production sites.

Can I run Moodle on Windows?

Yes. Moodle runs on Windows Server with IIS or Apache. For development purposes, XAMPP or WampServer work well. For production, Windows Server with IIS and SQL Server or MySQL is supported.

Can I use SQLite with Moodle?

No. Moodle does not support SQLite. You must use MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, or Oracle.

Can I install Moodle using Docker?

Yes. While Moodle does not provide official Docker images, several community-maintained Docker images are available. Bitnami provides a well-maintained Moodle Docker image. The basic setup involves:

docker run -d --name moodle 
  -p 80:8080 -p 443:8443 
  -e MOODLE_DATABASE_HOST=mariadb 
  -e MOODLE_DATABASE_USER=moodle 
  -e MOODLE_DATABASE_PASSWORD=secret 
  -e MOODLE_DATABASE_NAME=moodle 
  bitnami/moodle:latest

How do I check if my server meets requirements?

Create a PHP info file in your web root to check your PHP configuration:

<?php phpinfo(); ?>

Access it via a browser and verify PHP version, loaded extensions, and configuration values. Important: Remove this file after checking, as it exposes sensitive server information.

The installer hangs or times out

• Increase max_execution_time in php.ini to 300 or more
• Use the CLI installer instead: php admin/cli/install.php
• Check if the database server is overloaded
• Verify network connectivity between the web server and database server