Deploying MediaWiki with Docker Compose – A Practical Guide

Why Docker Compose for MediaWiki?

MediaWiki powers Wikipedia and thousands of community wikis. Running it in Docker gives you isolation, repeatable builds and easy scaling. Docker is the official container platform supported by the MediaWiki project, and the MediaWiki‑Docker development environment provides a ready‑made docker‑compose.yml that can be adapted for production use.

Prerequisites

• Docker Engine (Docker Desktop on macOS/Windows or Docker CE on Linux).
• Docker Compose plugin (v2+), which is bundled with recent Docker releases.
• A modest amount of disk space (≈1 GB for the images, plus storage for your wiki data).
• Basic familiarity with docker compose commands.

The MediaWiki‑Docker documentation notes that the environment works best on AMD64; ARM64 machines (e.g. M1 Macs) can run the images via Rosetta emulation.

Step‑by‑step Quickstart

1. Run the installer. Open http://localhost:8080 in a browser. The MediaWiki installer will ask for the database host (use db), name, user and password – the values you placed in .env. Fill in the site name, admin account and click *Install*.

Persist the configuration. After a successful install MediaWiki offers a LocalSettings.php file. Save it into the project root and uncomment the volume line in docker-compose.yml:

    volumes:
      - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
      - mediawiki-images:/var/www/html/images

Then restart the service:

docker compose restart mediawiki

Your wiki is now fully functional and the configuration is stored on the host.

Bring up the stack.

docker compose up -d

Docker will pull the official mediawiki and mysql:5.7 images (or mariadb if you prefer) and start two containers: mediawiki (Apache + PHP) and db.

Create a .env file. The .env variables are read by Docker Compose and injected into the containers. A minimal example:

# Core wiki settings
MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080
MW_DOCKER_PORT=8080

# Database credentials
MYSQL_ROOT_PASSWORD=strong_root_pw
MYSQL_DATABASE=mediawiki
MYSQL_USER=mediawiki
MYSQL_PASSWORD=strong_wiki_pw

# Optional debugging
XDEBUG_CONFIG=start_with_request=yes
XDEBUG_ENABLE=true

The MediaWiki‑Docker page lists the same variables and explains that you can add custom overrides later.

Clone the MediaWiki source. The development environment lives inside the MediaWiki repository itself. Run:

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

This gives you the docker-compose.yml file that ships with the core.

Understanding the Compose File

The default docker-compose.yml from MediaWiki‑Docker looks like this (simplified):

version: '3.8'
services:
  mediawiki:
    image: mediawiki:latest
    ports:
      - "${MW_DOCKER_PORT:-8080}:80"
    env_file: .env
    depends_on:
      - db
    volumes:
      - mediawiki-images:/var/www/html/images
      # LocalSettings.php is added after installation
  db:
    image: mysql:5.7
    env_file: .env
    volumes:
      - db-data:/var/lib/mysql
volumes:
  mediawiki-images:
  db-data:

Key points:

• Ports. The host port is taken from MW_DOCKER_PORT (default 8080).
• Environment. All variables are read from .env. The same file also sets MySQL passwords, which the Docker images honour automatically.
• Volumes. Two named volumes keep the wiki uploads (mediawiki-images) and the database data (db-data) persistent across container recreation.
• Dependency. depends_on ensures the DB starts first; the MediaWiki container will retry until the DB is reachable.

Extending the Stack – docker‑compose.override.yml

MediaWiki‑Docker encourages the use of an override file for customisation. Place a docker-compose.override.yml next to the original file and add any service‑level tweaks you need. Examples from the official documentation include:

• Replacing the database. Swap MySQL for MariaDB or PostgreSQL by changing the image line and adjusting environment variables.
• Adding a cache layer. Include memcached or redis services and point MediaWiki to them via $wgMainCacheType in LocalSettings.php.

Adding Xdebug. For PHP debugging you can enable the Xdebug extension and expose the IDE host:

services:
  mediawiki:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      XDEBUG_CONFIG: "client_host=host.docker.internal client_port=9003"
      XDEBUG_ENABLE: "1"

After editing the override file, run docker compose down && docker compose up -d to apply the changes.

Production‑grade Considerations

The MediaWiki‑Docker page makes it clear that there are no official production images. The images on Docker Hub are community‑maintained and suitable for most small‑to‑medium deployments, but for high‑traffic sites you should treat them as a starting point and apply hardening measures:

1. Use a non‑root user. Add a custom Dockerfile that switches to a low‑privilege UID/GID (the MW_DOCKER_UID and MW_DOCKER_GID variables help the container match the host’s file permissions).
2. Enable HTTPS. Terminate TLS at a reverse proxy (NGINX, Traefik or Caddy) sitting in front of the MediaWiki container. The proxy can be added as another service in the same compose file.
3. Limit resources. Use Docker’s deploy.resources stanza (or mem_limit, cpus) to cap RAM and CPU for the PHP container.
4. Regular backups. Schedule docker exec db /usr/bin/mysqldump -u${MYSQL_USER} -p${MYSQL_PASSWORD} ${MYSQL_DATABASE} > backup.sql and copy the mediawiki-images volume to a safe location.
5. Security updates. Pull the latest MediaWiki image weekly and run docker compose up -d --pull. The docker compose pull command fetches patched PHP, Apache and MySQL versions.

Adding Extensions & Skins

One of MediaWiki’s strengths is its extensibility. To add an extension you have two options:

• Composer install. Run docker compose exec mediawiki composer require mediawiki/cite. The Composer command installs the extension inside the container and updates composer.lock. Commit the lock file to version control for reproducibility.

Mount the source. Clone the extension repository into a host directory (e.g. extensions/Cite) and add a volume mapping in docker‑compose.override.yml:

services:
  mediawiki:
    volumes:
      - ./extensions/Cite:/var/www/html/extensions/Cite:cached

After the container restarts, enable the extension in LocalSettings.php with wfLoadExtension( 'Cite' );.

Skins are handled the same way – mount a skins/Vector directory or install via Composer.

Debugging & Development Tools

When you need to step‑through PHP code, enable Xdebug as shown earlier and configure your IDE to listen on port 9003. The XDEBUG_TRIGGER=1 environment variable can be added to a request query string to turn debugging on for a single page load.

For API testing, MediaWiki ships with a maintenance/run.php entry point. You can invoke it from the container:

docker compose exec mediawiki php maintenance/run.php update

This runs the database schema updates after you install a new extension.

Putting It All Together – A Sample Production Compose

version: '3.9'
services:
  mediawiki:
    image: mediawiki:latest
    restart: unless-stopped
    ports:
      - "80:80"
    env_file: .env
    depends_on:
      - db
    volumes:
      - mediawiki-images:/var/www/html/images
      - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
      - ./extensions:/var/www/html/extensions:cached
    extra_hosts:
      - "host.docker.internal:host-gateway"
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

  db:
    image: mariadb:10.11
    restart: unless-stopped
    env_file: .env
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  proxy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
    depends_on:
      - mediawiki

volumes:
  mediawiki-images:
  db-data:

This example adds a Caddy reverse proxy for TLS termination, uses MariaDB, limits resources and mounts a host extensions directory for easy development.

Conclusion

Deploying MediaWiki with Docker Compose is straightforward once you understand the three moving parts: the MediaWiki container, a database container, and optional services such as a reverse proxy or caching layer. The official MediaWiki‑Docker repository supplies a solid baseline, while docker‑compose.override.yml lets you tailor the stack for debugging, extensions, or production hardening. By keeping configuration in version‑controlled files and persisting data with named volumes, you get a reproducible, portable wiki that can grow from a personal knowledge base to a high‑availability community site.