By MW in guides — 12 Dec 2024

How to set up a local MediaWiki instance using Docker Compose

Running a MediaWiki wiki on your own laptop is a great way to experiment with extensions, skins, or just learn the platform. The official MediaWiki‑Docker development environment provides a ready‑made docker‑compose stack that works on Windows, macOS and Linux. This guide walks you through the whole process – from installing Docker to accessing your fresh wiki – in a concise, step‑by‑step manner.

Prerequisites

Docker Engine (Docker Desktop on Windows/macOS or the Docker daemon on Linux). Minimum version 20.10.
Docker Compose (v2 plugin is bundled with recent Docker releases).
Git (to clone the MediaWiki source). On Linux you can install git via your package manager.
A terminal with bash or zsh support.

If you already have Docker running, verify the installation:

docker version
docker compose version

Clone the MediaWiki‑Docker repository

The development environment lives inside the MediaWiki core repository. Run the quick‑setup wizard to pull the code and create the basic docker‑compose.yml file.

# Choose a folder for the wiki
mkdir ~/mywiki && cd ~/mywiki

# Start the wizard (it will ask a few questions)
mw docker mediawiki create

The wizard asks for:

Port on which the wiki will be reachable (default 8080).
Whether to clone a fresh MediaWiki core or use an existing directory.
Whether to include the Vector skin and any extensions.

After the wizard finishes you will have a directory layout similar to:

.
├─ docker-compose.yml          # Base stack (MediaWiki + SQLite)
├─ .settings/                # Helper scripts used by the dev environment
├─ extensions/                # Optional extensions you chose
└─ skins/                     # Optional skins you chose

Understanding the default stack

The generated docker‑compose.yml runs two services:

mediawiki – the PHP‑FPM container that hosts the wiki code.
mediawiki‑web – an Apache container that proxies HTTP requests to the PHP container.

By default the stack uses an SQLite database stored inside the container. This is perfect for a quick demo, but most real‑world tests need MySQL/MariaDB or PostgreSQL. The Alternative databases recipe shows how to replace SQLite with a proper DB server.

Adding a MariaDB service (recommended)

Create a docker-compose.override.yml in the same directory. Docker Compose automatically merges this file with the base file.

services:
  mariadb:
    image: bitnami/mariadb:latest
    environment:
      - MARIADB_ROOT_PASSWORD=secret_root
      - MARIADB_DATABASE=mediawiki
      - MARIADB_USER=wikiuser
      - MARIADB_PASSWORD=secret_pass
    ports:
      - "3306:3306"
    volumes:
      - mariadb_data:/bitnami/mariadb

volumes:
  mariadb_data:
    driver: local

Now the stack consists of three containers: mediawiki, mediawiki‑web, and mariadb. The MediaWiki container will detect the MEDIAWIKI_DB_HOST environment variable (set automatically by the dev environment) and use the new MySQL backend.

Start the stack

From the project root run:

docker compose down   # clean any previous run
docker compose up -d   # start in detached mode

Check that all services are up:

docker compose ps
# Expected output (example)
NAME                COMMAND               STATE          PORTS
mywiki_mediawiki-1  /mwdd/entrypoint.sh   Up             9000/tcp
mywiki_mediawiki-web-1  /entrypoint.sh   Up             0.0.0.0:8080->80/tcp
mywiki_mariadb-1    /opt/bitnami/scripts   Up             0.0.0.0:3306->3306/tcp

Run the MediaWiki installer

The container includes the MediaWiki install.php script. The easiest way is to open the wiki URL in a browser and let the web installer guide you.

Open http://localhost:8080 (or the port you chose).
Select your language and click “Continue”.
On the “Database settings” page, choose “MySQL” and fill in the credentials you set in the override file:
- Database host: mariadb
- Database name: mediawiki
- Database user: wikiuser
- Database password: secret_pass
Finish the wizard – it will create LocalSettings.php inside the container.

If you prefer a fully automated install, you can run the maintenance script from the host:

docker compose exec mediawiki php maintenance/install.php \
  --dbname=mediawiki \
  --dbuser=wikiuser \
  --dbpass=secret_pass \
  --dbserver=mariadb \
  --scriptpath=/w \
  --server="http://localhost:8080" \
  --lang=en "My Local Wiki" Admin adminpassword

This command creates LocalSettings.php in the container’s /var/www/html directory and makes the wiki immediately usable.

Persisting configuration and uploads

By default the dev environment stores the wiki files inside the container’s filesystem, which disappears when the container is removed. To keep your uploads and LocalSettings.php across restarts, bind‑mount a host directory. Add the following to the docker-compose.yml under the mediawiki service:

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

Now any uploaded files are saved to ./images on your host, and you can edit LocalSettings.php directly.

Adding extensions or skins

The wizard can already pull a few extensions, but you can add more manually:

# Example: add the Cite extension
cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Cite
cd ..
# Re‑run composer inside the container to install dependencies
docker compose exec mediawiki composer update
# Enable the extension in LocalSettings.php
cat >> LocalSettings.php <<'EOF'
wfLoadExtension( 'Cite' );
EOF

After editing LocalSettings.php reload the wiki in the browser – the new extension is active.

Customising the base image (optional)

If you need extra system packages (e.g., imagemagick for thumbnail generation), create a custom Dockerfile and reference it in an override file. See the Customize base image recipe.

services:
  mediawiki:
    build:
      context: ./docker
      dockerfile: Dockerfile

And ./docker/Dockerfile could be:

FROM docker-registry.wikimedia.org/dev/bookworm-php83-fpm:1.0.0
RUN apt-get update && apt-get install -y imagemagick && rm -rf /var/lib/apt/lists/*

Run docker compose build and then docker compose up -d again.

Stopping and cleaning up

When you are done experimenting, shut down the stack:

docker compose down

If you want to remove the database volume as well:

docker compose down -v

This deletes the mariadb_data volume, returning you to a clean slate.

Recap of the whole workflow

Install Docker and Git.
Run mw docker mediawiki create to generate the base compose file.
Create docker-compose.override.yml with a MariaDB service (or PostgreSQL).
Start the stack with docker compose up -d.
Run the web installer or the maintenance/install.php script.
Mount LocalSettings.php and images for persistence.
Add extensions, skins, or a custom base image as needed.
Stop the stack with docker compose down when finished.

Following these steps gives you a fully functional MediaWiki instance that you can tinker with locally, without affecting any production wiki. The same stack can be extended with Redis, ElasticSearch, or a job‑runner by adding the corresponding recipes from the MediaWiki‑Docker documentation.