Configuration

After installation, MediaWiki’s behaviour is controlled by LocalSettings.php in the root of your installation. This file is generated by the installer and must be customised for your deployment.

LocalSettings.php Overview

LocalSettings.php is a PHP file executed on every request. It sets global variables that override defaults defined in includes/MainConfigSchema.php. Variable names follow the $wg prefix convention (e.g. $wgSitename, $wgDBtype).

<?php
# This file was automatically generated by the MediaWiki 1.46 installer.
# If you make manual changes, please keep track in case you need to
# re-run the installer.

$wgSitename = 'My Wiki';
$wgServer   = 'https://wiki.example.com';
$wgScriptPath = '';

$wgDBtype     = 'mysql';
$wgDBserver   = 'localhost';
$wgDBname     = 'my_wiki';
$wgDBuser     = 'wikiuser';
$wgDBpassword = 'secret';

$wgSecretKey = 'put a long random string here';

Never commit LocalSettings.php to a public repository. It contains database credentials and your $wgSecretKey.

Essential Settings

Site Identity

Variable	Default	Description
`$wgSitename`	`'MediaWiki'`	Name of the wiki. Shown in the browser title bar and email notifications. Must be changed.
`$wgServer`	`false`	Full URL of the server (e.g. `'https://wiki.example.com'`). Must be set.
`$wgScriptPath`	(auto)	Relative URL path to the MediaWiki root (e.g. `'/wiki'` or `''` for the domain root).
`$wgArticlePath`	(auto)	URL pattern for articles. Defaults to `"$wgScriptPath/index.php?title=$1"`.

$wgSitename   = 'Acme Corp Wiki';
$wgServer     = 'https://wiki.acme.com';
$wgScriptPath = '';

Security Key

$wgSecretKey must always be set to a long, random string. It is used to sign cookies, session tokens, and other security-sensitive values.

$wgSecretKey = 'paste a 64-character random hex string here';

Generate a suitable value with:

LC_ALL=C tr -dc 'a-f0-9' < /dev/urandom | head -c 64; echo

If $wgSecretKey is not set or is weak, sessions can be forged and user accounts compromised.

Database Configuration

MySQL / MariaDB
PostgreSQL
SQLite

Requires the mysqli PHP extension.

$wgDBtype     = 'mysql';
$wgDBserver   = 'localhost';
$wgDBname     = 'my_wiki';
$wgDBuser     = 'wikiuser';
$wgDBpassword = 'secret';
# Optional: table name prefix, useful when sharing one database
$wgDBprefix   = '';
# Optional: connect over SSL
$wgDBssl      = false;

Create the database and user before running the installer:

CREATE DATABASE my_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'wikiuser'@'localhost' IDENTIFIED BY 'secret';
GRANT ALL PRIVILEGES ON my_wiki.* TO 'wikiuser'@'localhost';
FLUSH PRIVILEGES;

Requires the pgsql PHP extension.

$wgDBtype     = 'postgres';
$wgDBserver   = 'localhost';
$wgDBport     = 5432;
$wgDBname     = 'my_wiki';
$wgDBuser     = 'wikiuser';
$wgDBpassword = 'secret';
# PostgreSQL schema (default: 'mediawiki')
$wgDBmwschema = 'mediawiki';

Create the role and database:

CREATE ROLE wikiuser WITH LOGIN PASSWORD 'secret';
CREATE DATABASE my_wiki OWNER wikiuser ENCODING 'UTF8';

Requires the pdo PHP extension. Suitable for small wikis and local development.

$wgDBtype = 'sqlite';
$wgDBname = 'my_wiki';
# Directory where the .sqlite file is stored (must be writable by the web server)
$wgSQLiteDataDir = __DIR__ . '/cache';

$wgDBuser and $wgDBpassword are ignored for SQLite.

The database file will be created at $wgSQLiteDataDir/my_wiki.sqlite. Ensure this directory is not web-accessible.

File Upload Configuration

File uploads are disabled by default. To enable them:

$wgEnableUploads  = true;
$wgUploadPath     = "$wgScriptPath/images";
$wgUploadDirectory = __DIR__ . '/images';

Variable	Default	Description
`$wgEnableUploads`	`false`	Set to `true` to allow users to upload files.
`$wgUploadPath`	`"$wgScriptPath/images"`	URL path to the upload directory.
`$wgUploadDirectory`	`"$IP/images"`	Filesystem path to the upload directory. Must be writable by the web server.

For image thumbnailing, install the gd or imagick PHP extension. For EXIF metadata display, install exif.

Ensure the images/ directory is writable:

chown www-data:www-data images/
chmod 755 images/

Email Configuration

Email is enabled by default ($wgEnableEmail = true). MediaWiki uses PHP’s mail() function unless you configure SMTP.

# Disable all email features
$wgEnableEmail     = false;
$wgEnableUserEmail = false;

SMTP

To send mail via a dedicated SMTP server, set $wgSMTP to an array:

$wgSMTP = [
    'host'     => 'smtp.example.com',
    'IDHost'   => 'example.com',
    'port'     => 587,
    'auth'     => true,
    'username' => '[email protected]',
    'password' => 'smtppassword',
];

Set $wgSMTP = false (the default) to use PHP’s mail() function instead.

Variable	Default	Description
`$wgEnableEmail`	`true`	Master switch for all email features (password resets, notifications).
`$wgEnableUserEmail`	`true`	Allow user-to-user email via Special:EmailUser.
`$wgEmailAuthentication`	`true`	Require email confirmation before sending notifications. Prevents spam relay.
`$wgSMTP`	`false`	SMTP configuration array, or `false` to use `mail()`.
`$wgPasswordSender`	`'apache@<hostname>'`	The `From` address for password reminders and notifications.

Cache Backends

By default, $wgMainCacheType is CACHE_NONE (constant 0), which disables caching. Enabling a cache significantly improves performance.

// Available constants:
// CACHE_ANYTHING  = -1
// CACHE_NONE      = 0
// CACHE_DB        = 1
// CACHE_MEMCACHED = 2  (requires $wgMemCachedServers)
// CACHE_ACCEL     = 3  (APCu)

APCu
Memcached
Redis
Database

Fastest option for single-server deployments. Requires the apcu PHP extension.

$wgMainCacheType    = CACHE_ACCEL;
$wgMessageCacheType = CACHE_ACCEL;
$wgParserCacheType  = CACHE_DB; // keep parser cache in DB

Recommended for multi-server deployments. Requires the memcached PHP extension.

$wgMainCacheType    = CACHE_MEMCACHED;
$wgMessageCacheType = CACHE_MEMCACHED;
$wgMemCachedServers = [ '127.0.0.1:11211' ];
$wgMemCachedPersistent = false;
$wgMemCachedTimeout = 500000; // microseconds

Requires the redis PHP extension. Register a custom ObjectCaches entry, then reference it:

$wgObjectCaches['redis'] = [
    'class'       => 'RedisBagOStuff',
    'servers'     => [ '127.0.0.1:6379' ],
    'persistent'  => true,
];
$wgMainCacheType    = 'redis';
$wgMessageCacheType = 'redis';
$wgSessionCacheType = 'redis';

No additional extensions required. Slower than in-memory backends but zero configuration.

$wgMainCacheType = CACHE_DB;

Key Security Settings

Variable	Default	Notes
`$wgSecretKey`	`false`	Must be set. Used to sign cookies and tokens.
`$wgForceHTTPS`	`false`	Set to `true` to redirect all HTTP requests to HTTPS.
`$wgEmailAuthentication`	`true`	Require email verification before sending mail. Prevents spam abuse.
`$wgEditPageFrameOptions`	`'DENY'`	Sends `X-Frame-Options: DENY` on edit pages to prevent clickjacking.
`$wgAllowUserJs`	`false`	Allow users to run custom JavaScript. Increases XSS risk.
`$wgAllowUserCss`	`false`	Allow users to apply custom CSS.
`$wgBreakFrames`	`false`	Set to `true` to break out of framesets on all pages.
`$wgDBssl`	`false`	Connect to the database over SSL (MySQL/MariaDB and PostgreSQL).

# Recommended production security settings
$wgForceHTTPS         = true;
$wgEmailAuthentication = true;
$wgEditPageFrameOptions = 'DENY';

Overview

Installation

Core Concepts

LocalSettings.php Overview

Essential Settings

Site Identity

Security Key

Database Configuration

File Upload Configuration

Email Configuration

SMTP

Cache Backends

Key Security Settings

Build docs developers (and LLMs) love

Overview

Installation

Core Concepts

​LocalSettings.php Overview

​Essential Settings

​Site Identity

​Security Key

​Database Configuration

​File Upload Configuration

​Email Configuration

​SMTP

​Cache Backends

​Key Security Settings

Build docs developers (and LLMs) love

LocalSettings.php Overview

Essential Settings

Site Identity

Security Key

Database Configuration

File Upload Configuration

Email Configuration

SMTP

Cache Backends

Key Security Settings