Configuration File

Configuration File (config.php)

The config.php file is the main configuration file for Moodle, located in the root of your Moodle installation directory. It is created during the installation process and contains essential settings for database connectivity, site URLs, data directories, and optional performance and debugging parameters.

Basic Structure

A minimal config.php file looks like this:

<?php
unset($CFG);
global $CFG;
$CFG = new stdClass();

$CFG->dbtype    = 'mysqli';
$CFG->dblibrary = 'native';
$CFG->dbhost    = 'localhost';
$CFG->dbname    = 'moodle';
$CFG->dbuser    = 'moodleuser';
$CFG->dbpass    = 'securepassword';
$CFG->prefix    = 'mdl_';
$CFG->dboptions = array(
    'dbpersist' => false,
    'dbsocket'  => false,
    'dbport'    => '',
    'dbhandlesoptions' => false,
    'dbcollation' => 'utf8mb4_unicode_ci',
);

$CFG->wwwroot   = 'https://yourmoodle.example.com';
$CFG->dataroot  = '/var/moodledata';
$CFG->admin     = 'admin';
$CFG->directorypermissions = 02777;

require_once(__DIR__ . '/lib/setup.php');

Database Settings

• $CFG->dbtype — Database driver: mysqli, mariadb, pgsql, sqlsrv, oci
• $CFG->dblibrary — Always native
• $CFG->dbhost — Database server hostname (use localhost or IP address)
• $CFG->dbname — Name of the Moodle database
• $CFG->dbuser — Database username
• $CFG->dbpass — Database password
• $CFG->prefix — Table name prefix (default mdl_). Allows multiple Moodle installations to share one database.

Core Path Settings

• $CFG->wwwroot — The full URL of your Moodle site, without a trailing slash. Must match the actual URL users access.
• $CFG->dataroot — Absolute path to the writable data directory, outside the web root.
• $CFG->admin — Name of the admin directory (default admin; some hosts require renaming this).
• $CFG->dirroot — Set automatically; the absolute path to the Moodle code directory. Do not set manually.

Debugging Settings

Add these settings to config.php (before the require line) to enable detailed error reporting during development or troubleshooting:

// Show all debug messages
@error_reporting(E_ALL | E_STRICT);
@ini_set('display_errors', '1');
$CFG->debug = (E_ALL | E_STRICT);
$CFG->debugdisplay = 1;

// Show detailed page information
$CFG->debugpageinfo = true;

// Show performance information in the page footer
$CFG->perfdebug = 15;

Important: Disable all debugging settings on production sites, as they can expose sensitive information.

Performance Settings

// Force specific cache stores in config
$CFG->cachedir = '/tmp/moodlecache';

// Allow more memory for specific scripts
$CFG->extramemorylimit = '1G';

// Enable content caching for less disk I/O
$CFG->localcachedir = '/tmp/moodlelocalcache';

// Prevent theme designer mode (better performance)
$CFG->themedesignermode = false;

// Force caching of language strings
$CFG->langstringcache = true;

// Pre-calculated course counts on category pages
$CFG->coursecontactcache = true;

Session Handling

// Use database sessions (default)
$CFG->session_handler_class = '\core\session\database';

// Or use file sessions
$CFG->session_handler_class = '\core\session\file';
$CFG->session_file_save_path = '/tmp/moodlesessions';

// Or use Redis for sessions
$CFG->session_handler_class = '\core\session\redis';
$CFG->session_redis_host = '127.0.0.1';
$CFG->session_redis_port = 6379;
$CFG->session_redis_database = 0;
$CFG->session_redis_prefix = 'moodle_session_';
$CFG->session_redis_acquire_lock_timeout = 120;
$CFG->session_redis_lock_expire = 7200;

Reverse Proxy and Load Balancer Settings

// If Moodle is behind a reverse proxy
$CFG->reverseproxy = true;
$CFG->sslproxy = true; // If SSL is terminated at the proxy

// If behind a load balancer, define trusted proxy IPs
$CFG->reverseproxywhitelist = '10.0.0.1, 10.0.0.2';

Email Settings via config.php

$CFG->smtphosts = 'smtp.example.com:587';
$CFG->smtpsecure = 'tls';
$CFG->smtpauthtype = 'LOGIN';
$CFG->smtpuser = 'user@example.com';
$CFG->smtppass = 'smtppassword';
$CFG->noreplyaddress = 'noreply@example.com';

Forcing Settings via config.php

You can override and lock any admin setting by adding it to config.php. Settings forced this way cannot be changed through the web interface:

// Force SMTP settings (cannot be changed in admin UI)
$CFG->forced_plugin_settings = [
    'auth_ldap' => [
        'host_url' => 'ldap://ldap.example.com',
    ],
];

Alternative Data Root for Temp Files

// Separate temp directory for better performance on some systems
$CFG->tempdir = '/tmp/moodletmp';
$CFG->cachedir = '/tmp/moodlecache';
$CFG->localcachedir = '/tmp/moodlelocalcache';

Security Considerations

• Set file permissions to 640 so only the owner and group can read the file: chmod 640 config.php
• Ensure the file is owned by root (or the deploying user) and readable by the web server group: chown root:www-data config.php
• Never store config.php in a publicly accessible version control repository
• Use environment variables for sensitive values in containerized environments