Sign in Subscribe
By MW in docker —

How to Deploy MediaWiki Using Docker Compose for Rapid Setup and Management

Introduction

MediaWiki powers Wikipedia and thousands of other wikis. Running it on a bare‑metal server is possible, but for most teams the real advantage comes from containerisation: a single command can spin up a fully functional wiki, and the whole stack can be version‑controlled, reproduced and moved between environments without manual configuration. This guide shows how to use MediaWiki‑Docker together with docker‑compose to achieve a rapid, repeatable deployment.

Why Docker Compose?

  • Isolation – each service (web, database, optional cache) runs in its own container, preventing library conflicts.
  • Portability – the same docker‑compose.yml works on a developer laptop, a CI runner and a production VM.
  • Declarative configuration – the entire stack is described in a single YAML file that can be stored in Git.
  • Easy management – docker compose up, down, restart and logs replace dozens of manual steps.

Prerequisites

Make sure the following are installed on the host where you intend to run the wiki:

  • Docker Engine (>= 20.10) – official install guide
  • Docker Compose plugin (or the legacy docker‑compose binary) – install guide
  • A non‑root user in the docker group (or use sudo for each command).

All commands below assume the current user can run docker without sudo.

Project layout

Create a dedicated directory for the wiki. The layout mirrors the example from the MediaWiki‑Docker page and keeps data separate from the container images.

mkdir -p ~/mediawiki-docker && cd $_
mkdir -p db_data mediawiki_images

The three top‑level items are:

  • docker-compose.yml – core stack definition.
  • .env – environment variables that keep secrets out of the YAML.
  • Two named volumes (db_data and mediawiki_images) that persist MySQL/MariaDB data and uploaded files.

.env – store credentials and basic settings

Copy the snippet below into a file called .env. Replace the placeholder values with strong passwords of your own.

# ------------------------------------------------------------
# MediaWiki Docker‑Compose configuration (environment file)
# ------------------------------------------------------------
# Database connection
MW_DB_HOST=db
MW_DB_NAME=mediawiki
MW_DB_USER=wikiuser
MW_DB_PASSWORD=SuperSecret123!

# Wiki identity (used during the web installer)
MW_SITE_NAME="My Dockerised Wiki"
MW_ADMIN_USER=admin
MW_ADMIN_PASSWORD=AdminPass456!
MW_SCRIPT_PATH=/w
MW_SERVER=http://localhost:8080

# Optional debug flags – set to 1 to enable Xdebug in the web container
XDEBUG_ENABLE=0

The .env file is automatically read by docker compose and interpolated into the compose file.

docker‑compose.yml – the core stack

The following file follows the official MediaWiki‑Docker defaults, adding a few production‑friendly tweaks such as healthchecks and explicit volume mounts for uploads.

version: "3.8"

services:
  # ------------------------------------------------------------
  # MediaWiki web container (PHP + Apache)
  # ------------------------------------------------------------
  mediawiki:
    image: mediawiki:latest
    container_name: mediawiki
    depends_on:
      - db
    ports:
      - "8080:80"                     # Host‑side port 8080 → container port 80
    environment:
      # Core MediaWiki variables – pulled from .env
      MEDIAWIKI_DB_HOST: ${MW_DB_HOST}
      MEDIAWIKI_DB_NAME: ${MW_DB_NAME}
      MEDIAWIKI_DB_USER: ${MW_DB_USER}
      MEDIAWIKI_DB_PASSWORD: ${MW_DB_PASSWORD}
      MEDIAWIKI_SITE_NAME: ${MW_SITE_NAME}
      MEDIAWIKI_ADMIN_USER: ${MW_ADMIN_USER}
      MEDIAWIKI_ADMIN_PASSWORD: ${MW_ADMIN_PASSWORD}
      MEDIAWIKI_SCRIPT_PATH: ${MW_SCRIPT_PATH}
      MEDIAWIKI_SERVER: ${MW_SERVER}
      # Optional Xdebug – see override file for details
      XDEBUG_ENABLE: ${XDEBUG_ENABLE}
    volumes:
      - mediawiki_images:/var/www/html/images   # Persistent uploads
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/w/api.php?action=query&meta=siteinfo"]
      interval: 30s
      timeout: 10s
      retries: 5

  # ------------------------------------------------------------
  # Database container – MySQL 5.7 (compatible with MediaWiki 1.35+)
  # ------------------------------------------------------------
  db:
    image: mysql:5.7
    container_name: mediawiki-db
    environment:
      MYSQL_DATABASE: ${MW_DB_NAME}
      MYSQL_USER: ${MW_DB_USER}
      MYSQL_PASSWORD: ${MW_DB_PASSWORD}
      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 30s
      timeout: 10s
      retries: 5

volumes:
  db_data:
    driver: local
  mediawiki_images:
    driver: local

Key points:

  • The mediawiki service pulls the official Docker Hub image (mediawiki:latest).
  • All secrets live in .env, keeping the YAML file safe for version control.
  • Healthchecks let docker compose know when a service is ready, which is useful for scripted CI pipelines.

Optional docker‑compose.override.yml – developer extras

If you intend to develop extensions or need Xdebug, create an override file that adds a bind‑mount for the source tree and enables Xdebug on demand. The MediaWiki‑Docker documentation lists many recipes; the following is a minimal example.

services:
  mediawiki:
    # Mount a local extensions directory – useful when you are building custom extensions
    volumes:
      - ./extensions:/var/www/html/extensions:cached
    # Enable Xdebug only when the env var is set to 1
    environment:
      XDEBUG_CONFIG: "client_host=host.docker.internal client_port=9003"
    extra_hosts:
      - "host.docker.internal:host-gateway"

After creating or editing the override file, recreate the stack:

docker compose down
docker compose up -d   # Docker will automatically merge the override

First start – bringing the stack up

Run the following command from the project root:

docker compose up -d

The command pulls the required images (MediaWiki, MySQL), creates the two named volumes and starts the containers in detached mode. You can watch the logs while the database initialises:

docker compose logs -f

When the mediawiki container reports “ready”, open a browser and navigate to http://localhost:8080. The MediaWiki web installer will appear.

Completing the MediaWiki web installer

  1. Database settings – use the values from .env (host db, name mediawiki, user wikiuser, password you set).
  2. Wiki name, admin user and password – the same values you set in .env are pre‑filled, but you can change them if you wish.
  3. When the installer finishes it offers a LocalSettings.php file for download. Save this file in the project root (next to docker‑compose.yml).

Now edit docker‑compose.yml and uncomment the line that mounts LocalSettings.php. If you are using the snippet from the MediaWiki‑Docker guide, the line looks like this (remove the leading #):

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

Restart the web container so the configuration is loaded:

docker compose restart mediawiki

Your wiki is now fully functional and persists data across container restarts.

Managing the stack

  • Stop: docker compose down – removes containers but keeps the named volumes.
  • Start: docker compose up -d
  • View logs: docker compose logs -f
  • Enter a container: docker compose exec mediawiki bash (useful for running maintenance scripts).
  • Run updates: docker compose exec mediawiki php maintenance/run.php update

Adding extensions and skins

The MediaWiki‑Docker environment makes it trivial to install extensions:

  1. Create a directory extensions in the project root.
  2. Make sure the docker‑compose.override.yml mounts the extensions folder (see the example above).

Restart the web container and run the update script:

docker compose restart mediawiki
docker compose exec mediawiki php maintenance/run.php update

Add a line to LocalSettings.php:

wfLoadExtension( 'Cite' );

Clone the desired extension repository into that directory, e.g.:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Cite extensions/Cite

Skins follow the same pattern – mount a skins directory and load them via wfLoadSkin().

Performance and security tips

  • Disable Xdebug in production – set XDEBUG_ENABLE=0 in .env. Xdebug adds noticeable latency.
  • Use a dedicated MySQL version – MediaWiki 1.35+ works well with MySQL 5.7 or MariaDB 10.5. Choose the image that matches your host architecture (ARM hosts need platform: linux/x86_64 for the official MySQL 5.7 image).
  • Enable a caching layer – for larger wikis add memcached or redis services and point $wgMainCacheType to them. The MediaWiki‑Docker page lists a memcached recipe.

Back up data – the named volumes hold all persistent data. A quick snapshot can be taken with:

docker run --rm -v mediawiki_images:/src -v $(pwd)/backup:/backup alpine tar czf /backup/mediawiki_images.tar.gz -C /src .

Restrict container privileges – run the web container as a non‑root user. Add to the service definition:

    user: "${MW_DOCKER_UID}:${MW_DOCKER_GID}"

Populate MW_DOCKER_UID and MW_DOCKER_GID in .env with the host UID/GID (e.g. $(id -u)).

Scaling out

For a production wiki you may want separate web, job‑runner and cache services. MediaWiki‑Docker already ships recipes for a jobrunner container that processes background jobs (e.g. email queues). Adding it is as simple as extending the compose file with the recipe from the Configuration recipes section.

Full example repository

All the files described in this article are available in a minimal Git repository that you can clone and customise:

git clone https://github.com/mediawiki/docker‑example.git
cd docker‑example
# edit .env, then:
docker compose up -d

Because the repository lives on MediaWiki’s own GitHub, it stays in sync with future version‑updates of the official Docker image.

Conclusion

Deploying MediaWiki with Docker Compose gives you a fast, reproducible and easily maintainable wiki platform. By keeping configuration in .env and using the official MediaWiki‑Docker recipes, you can move from a local test instance to a production‑grade deployment with only a few lines of YAML. The same stack can be extended with custom extensions, skins, caching services or a job‑runner, making Docker Compose a solid foundation for both hobby wikis and large‑scale knowledge bases.

Subscribe to MediaWiki Tips and Tricks

Don’t miss out on the latest articles. Sign up now to get access to the library of members-only articles.
jamie@example.com
Subscribe