How to Set Up MediaWiki with Docker Compose for Local Development

MediaWiki powers Wikipedia and thousands of wikis worldwide. For developers, contributors, or anyone who wants a sandbox to experiment with extensions, the official MediaWiki‑Docker development environment provides a ready‑made Docker stack. This guide walks you through the entire process – from pulling the source repository to having a fully‑functional wiki running on http://localhost:8080 – using docker‑compose on a local machine.

1. Prerequisites

• Docker Engine (≥ 20.10) and Docker Compose (v2 syntax). Both are available for Linux, macOS and Windows.
• Git – to clone the MediaWiki core repository.
• A modern web browser for the installation wizard.

All three tools can be installed via the official Docker website or your OS package manager.

2. Clone the MediaWiki core repository

The Docker development environment lives inside the MediaWiki source tree. Clone the mediawiki repository (the default branch is master as of 2025) and change into the directory:

git clone https://gerrit.wikimedia.org/r/mediawiki/core.git
cd core

At this point you have a docker-compose.yml file generated by the project – it defines a mediawiki service and a database service (MariaDB by default).

3. Quick‑start with the default stack

The quickstart on MediaWiki‑Docker claims a 15‑minute setup. Run the following command to pull the images and start the containers in the background:

docker compose up -d

Docker will download two images:

• mediawiki:latest – the web application (PHP + Apache).
• mariadb:10.5 (or mysql:5.7 for older tutorials) – the database.

When the containers are healthy, open http://localhost:8080. You will see the MediaWiki installation wizard.

4. Persistent data – why you need a Docker‑Compose override

The default stack stores uploads, configuration and the database in anonymous Docker volumes. Those volumes disappear when you run docker compose down -v. For a local development environment you usually want:

• Wiki images (uploaded files) in ./images.
• Database files in ./db.
• A persistent LocalSettings.php file that tells MediaWiki where the database lives.

Create a file called docker-compose.override.yml next to the original docker-compose.yml with the following content:

services:
  mediawiki:
    volumes:
      - ./images:/var/www/html/images
      # After the installation wizard you will download LocalSettings.php.
      # Uncomment the line below and restart the stack to mount it.
      # - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
  database:
    volumes:
      - ./db:/var/lib/mysql

Docker Compose automatically merges the override into the base file, giving you a persistent layout without altering the official configuration.

5. Run the installer and capture LocalSettings.php

1. Visit http://localhost:8080 and follow the wizard.
   • Database type: MySQL/MariaDB
   • Host name: database (the service name defined in docker‑compose.yml)
   • Database name, user and password – use the defaults from the file (mediawiki/mediawiki).
2. Complete the site configuration (site name, admin account, etc.).
3. When the wizard finishes it offers a LocalSettings.php download. Save it into the project root (the same directory as the compose files).

Now edit docker-compose.override.yml and uncomment the line that mounts the settings file:

      - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro

Restart the stack so the web container reads the new configuration:

docker compose down
docker compose up -d

The wiki should now load without asking for installation again.

6. Optional: use an .env file for secret values

Hard‑coding passwords in docker‑compose.yml is fine for a throw‑away sandbox, but a small .env file makes it easier to change credentials and keeps them out of version control.

# .env – keep this file private
MYSQL_ROOT_PASSWORD=verySecretRoot
MYSQL_DATABASE=mediawiki
MYSQL_USER=mediawiki
MYSQL_PASSWORD=verySecretPass

Then reference the variables in the compose file:

services:
  database:
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}

Docker Compose automatically loads .env from the same directory.

7. Adding extensions for development

The Docker environment ships with a minimal PHP image. To test extensions you can either:

• Mount a extensions directory into /var/www/html/extensions and place the unpacked extension there.
• Use the docker compose exec mediawiki bash command to install Composer‑based extensions directly inside the container.

Example – adding the Echo extension:

mkdir -p extensions/Echo
cd extensions/Echo
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Echo.git .
# Back to the project root and restart the container
docker compose up -d

Finally add the extension to LocalSettings.php:

wfLoadExtension( 'Echo' );

Because LocalSettings.php is mounted read‑only, you can edit it on the host and the change is reflected instantly.

8. Common troubleshooting tips

Problem	Typical cause	Fix
Container fails to start (exit code 1)	Missing environment variables or wrong password	Check docker compose logs database for MySQL errors; verify .env values.
“Cannot connect to database” during installer	Wrong host name	Use the service name database – not localhost – because the web container runs in a separate network.
Uploads are not persisted	Images volume not mounted	Make sure ./images:/var/www/html/images is present in the override and that the directory exists on the host.
PHP errors after adding an extension	Missing PHP extensions (e.g., intl)	Add a custom Dockerfile that extends mediawiki:latest and installs the required packages, then reference it in docker-compose.override.yml.

9. Stopping and cleaning the environment

When you are done experimenting, bring the stack down:

docker compose down

If you also want to delete the anonymous volumes (useful for a fresh start), add the -v flag:

docker compose down -v

Because the images and db directories are bind‑mounted, they remain on the host and can be inspected or backed up manually.

10. Next steps

• Explore the official extension list and try them out locally.
• Integrate a reverse‑proxy (NGINX or Traefik) for HTTPS and custom domains.
• For more realistic performance testing, switch the database service to postgres or elasticsearch and use the provided configuration recipes in MediaWiki‑Docker.
• Check the configuration recipes for XDebug, Memcached, or OpenSearch.

With this Docker Compose setup you have a fully‑functional MediaWiki that can be torn down, rebuilt, and extended in minutes – an ideal playground for developers, documentation writers, and anyone curious about the software behind Wikipedia.