Deploying MediaWiki with Docker Compose – A Practical Guide

Docker Compose is the most common way to run MediaWiki outside shared hosting: the official MediaWiki image (Apache + PHP) works with a MariaDB or MySQL container, and everything is described in one docker-compose.yml. This guide covers a production-oriented setup — persistent storage, configuration via volume mounts, backups and upgrades. (For day-to-day extension development, MediaWiki core's own MediaWiki-Docker environment is the better starting point; this article is about running a real wiki.)

The compose file

services:
  mediawiki:
    image: mediawiki:lts   # or a pinned version like mediawiki:1.43
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      MEDIAWIKI_DB_HOST: db
      MEDIAWIKI_DB_NAME: mediawiki
      MEDIAWIKI_DB_USER: mediawiki
      MEDIAWIKI_DB_PASSWORD: "${MW_DB_PASSWORD}"
    volumes:
      - mw-images:/var/www/html/images
      - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
    depends_on:
      - db

  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: "${MW_DB_ROOT_PASSWORD}"
      MARIADB_DATABASE: mediawiki
      MARIADB_USER: mediawiki
      MARIADB_PASSWORD: "${MW_DB_PASSWORD}"
    volumes:
      - db-data:/var/lib/mysql

volumes:
  mw-images:
  db-data:

Environment values go in a local .env file (never committed):

MW_DB_PASSWORD=strong-password-here
MW_DB_ROOT_PASSWORD=strong-root-password-here

Start the stack, then walk through the installer at http://localhost:8080 — use database host db and the credentials above. The installer produces a LocalSettings.php; save it next to the compose file and re-run docker compose up -d so the container picks it up.

Volume strategy

• mw-images — uploads live here; without the volume they vanish on container recreation, which happens on every image update
• db-data — the MariaDB datadir; the single most valuable volume on the system
• LocalSettings.php — mounted read-only. Install extensions by mounting them under /var/www/html/extensions (e.g. ./extensions/PageForms:/var/www/html/extensions/PageForms:ro) — or better, build your own image from the official one that bakes extensions and config in, so a docker compose pull reproduces everything

Upgrades

The official image tracks MediaWiki releases as tags; mediawiki:lts follows LTS lines. The upgrade procedure is the normal MediaWiki one inside containers:

1. Dump the database first: docker compose exec db mariadb-dump -u root -p"$MW_DB_ROOT_PASSWORD" mediawiki > backup.sql
2. Pin — change the image tag to the new version in the compose file
3. docker compose up -d mediawiki && docker compose exec mediawiki php maintenance/run.php update
4. Check Special:Version and the mediawiki container logs for deprecation warnings from extensions

Every major version bump requires the updater; skipping it breaks the wiki with a clear "please run update" message. Read the upgrade manual before any LTS-crossing upgrade.

Backups

A minimal but complete backup is the database dump plus the mw-images volume contents:

docker compose exec db mariadb-dump --single-transaction -u root -p"$MW_DB_ROOT_PASSWORD" mediawiki > wiki-$(date +%F).sql
# images volume:
docker run --rm -v mediawiki_mw-images:/data -v $PWD:/backup alpine tar czf /backup/images-$(date +%F).tgz -C /data .

Restore = recreate volumes, import the dump, unpack the images. Test the restore at least once — backups that are never restored are a ritual, not a safety net.

Notes and limits

• Performance — the default image runs Apache with a stock PHP configuration; for production throughput, mount an opcache tuning INI or move to a PHP-FPM/nginx setup later. Start simple, measure, then tune
• Search — the built-in search works out of the box; wiring CirrusSearch + Elasticsearch is additional compose services and significant RAM, so delay it until the wiki actually needs it
• Backing — put the whole stack behind HTTPS; see the MediaWiki Let's Encrypt guide for the reverse-proxy setup

Compose is not the end-state architecture for a Wikipedia-scale deployment, but for a self-hosted wiki it is a clean, reproducible, backup-friendly way to run MediaWiki. The official image documentation covers the remaining details.