MediaWiki represents the gold standard in free and open-source wiki software, serving as the foundational engine for some of the most visited sites on the internet, including Wikipedia, Wiktionary, and Wikimedia Commons. Originally conceptualized by Magnus Manske and further refined by Lee Daniel Crocker, the software is engineered using the PHP programming language and utilizes a database backend for persistent content storage. Due to its architectural similarities to WordPress in terms of licensing and structure, MediaWiki has established itself as the dominant force in the wiki software category. For the modern developer or system administrator, deploying this powerhouse via Docker transforms a traditionally complex installation into a streamlined, containerized process that ensures environment parity across different hosting infrastructures.
The Core Technical Architecture of MediaWiki Containers
The deployment of MediaWiki through Docker is designed to abstract the underlying operating system and PHP environment, providing a consistent runtime. The images are maintained through a collaborative effort between the MediaWiki community and the Docker Community, ensuring that the core software is packaged with the necessary dependencies to function immediately upon instantiation.
The fundamental design of the official MediaWiki image is that of a base runtime. It is intentionally lean to prevent unnecessary bloat. Because MediaWiki supports a vast array of plugins and extensions, and because these extensions may require any PHP extension that exists, the maintainers have opted not to include every possible PHP library by default. Including every possible extension would lead to a catastrophic increase in image size, rendering the container inefficient for distribution and deployment.
For users requiring specialized PHP extensions, the official image serves as a base. Developers can create a custom image using the FROM mediawiki instruction in a Dockerfile. The process for compiling additional extensions follows the standard procedures outlined in the official PHP image documentation, allowing for a tailored environment that meets specific organizational needs without compromising the stability of the core image.
Deployment Methodologies and Execution
Depending on the requirements of the user—whether they are testing a feature or deploying a production-grade wiki—there are several ways to initiate a MediaWiki instance.
Single Container Execution
For rapid prototyping or "throw-away" testing, the most basic pattern is to run a single container using the docker run command. This method is ideal for users who want to verify the software's behavior without committing to a full infrastructure setup.
To start a basic instance:
docker run --name some-mediawiki -d mediawiki
In this scenario, the container runs in detached mode (-d), and is named some-mediawiki. However, this basic command does not map ports to the host machine, meaning the instance is only accessible via the container's internal IP address. To make the wiki accessible via a web browser on the host machine, standard port mapping must be employed.
To map the container's internal port 80 to the host's port 8080:
docker run --name some-mediawiki -p 8080:80 -d mediawiki
Once this command is executed, the instance can be accessed through http://localhost:8080 or http://host-ip:8080.
Orchestrated Deployment via Docker Compose
For actual utility, MediaWiki requires a database. Manually linking containers is cumbersome; therefore, Docker Compose is the recommended standard for managing the multi-container architecture consisting of the MediaWiki application and a database engine (such as MariaDB).
A standard compose.yaml or docker-compose.yml configuration involves defining two primary services: the mediawiki service and the database service.
The following table outlines the technical specifications for a standard Compose deployment:
| Component | Image | Port Mapping | Key Volume | Role |
|---|---|---|---|---|
| MediaWiki | mediawiki |
8080:80 |
/var/www/html/images |
Application Logic & Web Server |
| Database | mariadb |
N/A | /var/lib/mysql |
Persistent Data Storage |
In a typical Compose configuration, the mediawiki service is configured with restart: always to ensure high availability. It links to the database service, allowing the PHP application to communicate with the database engine using the service name as the hostname.
Step-by-Step Installation and Configuration Workflow
Installing MediaWiki via Docker is a multi-stage process that involves initial container orchestration followed by a web-based configuration wizard.
Phase 1: Initial Orchestration
The process begins with the creation of a dedicated project folder. Inside this folder, a docker-compose.yml file is created. This file defines the desired state of the infrastructure, including environment variables for the database.
For a MariaDB setup, the following environment variables are critical:
- MYSQL_DATABASE: Defines the name of the wiki database (e.g., my_wiki).
- MYSQL_USER: The username for the database (e.g., wikiuser).
- MYSQL_PASSWORD: The password for the database user.
- MYSQL_RANDOM_ROOT_PASSWORD: Set to 'yes' to generate a secure root password automatically.
To initiate the services, the user executes:
docker compose up -d
This command pulls the necessary images from Docker Hub and starts the containers in the background.
Phase 2: The Web Installation Wizard
Once the containers are operational, the user must navigate to http://localhost:8080 in a web browser. This triggers the standard MediaWiki installation procedure. During this phase, the user configures the database connection using the credentials defined in the Compose file.
A critical outcome of this wizard is the generation of the LocalSettings.php file. This file contains all the configuration settings for the wiki instance. MediaWiki will prompt the user to download this file.
Phase 3: Persisting Configuration
The LocalSettings.php file is the brain of the installation. Without it, the container will revert to the installation wizard every time it restarts. To persist the configuration, the following steps must be taken:
- Save the downloaded
LocalSettings.phpfile in the same directory as thedocker-compose.ymlfile. - In the
docker-compose.ymlfile, locate the volumes section for the mediawiki service. - Un-comment the line mapping the local file to the container path:
- ./LocalSettings.php:/var/www/html/LocalSettings.php - Shut down the containers to apply the changes:
docker compose down - Bring the containers back up:
docker compose up -d
At this stage, the folder structure should consist of the docker-compose.yml file, the LocalSettings.php file, and two data folders: db_data and mediawiki_data. The wiki is now fully operational, and the user can log in with the account created during the installation wizard.
Image Variants and Selection Criteria
The Docker Hub provides different "flavors" of the MediaWiki image to accommodate various deployment needs and hardware architectures.
The Default Image (mediawiki:<version>)
This is the defacto image and the recommended choice for the vast majority of users. It is designed for versatility, functioning both as a throw-away container—where source code is mounted for rapid application testing—and as a robust base image for building specialized versions.
The Alpine Image (mediawiki:<version>-alpine)
Based on the Alpine Linux project, this image is significantly smaller than the default version. It is optimized for environments where storage and memory are constrained, providing a minimal footprint while maintaining the core functionality of the MediaWiki software.
Hardware Compatibility and Architecture Troubleshooting
A significant technical hurdle occurs when deploying these containers on Apple Silicon (M1 chips). Specifically, the mysql:5.7 image often fails installation because there is no ARM-compatible binary available for that particular version of MySQL.
To resolve this architectural mismatch, users have two primary options:
- Force the AMD64 version by adding the
platform: linux/x86_64directive to the database service in thedocker-compose.ymlfile. This allows the image to run via emulation, though it may incur a performance penalty. - Replace the MySQL image with a MariaDB image, which generally provides better compatibility and performance on ARM-based systems.
If the wiki is used for low-concurrency edits, the performance hit from emulation may be negligible, but for high-traffic instances, the MariaDB alternative is the superior technical choice.
Maintenance, Contributions, and Bug Reporting
The MediaWiki Docker ecosystem is maintained through a rigorous process involving both the MediaWiki and Docker communities. To maintain the integrity of the official images, specific protocols are in place for updates and reporting.
Update Process
The Dockerfiles for MediaWiki should not be edited directly by the community. Instead, the project utilizes a template-based system. Changes must be made in the Dockerfile-*.template files. These changes are then applied by executing the update.py script.
To ensure the images are consistently current, a scheduled GitHub Action runs update.py once per day. This automated pipeline ensures that the latest security patches and software updates are integrated into the official images.
Tracking Changes
Users wishing to track changes that have been merged but not yet published to Docker Hub can monitor the library/mediawiki manifest file within the docker-library/official-images repository. Specifically, Pull Requests (PRs) labeled with library/mediawiki provide a transparent view of upcoming changes to the image.
Reporting Issues
To ensure that bugs are tracked by the appropriate developers, the project mandates that bug reports be filed on Phabricator rather than GitHub. The designated project view for reporting issues is:
https://phabricator.wikimedia.org/project/view/3094/
Comparative Analysis of Deployment Approaches
The choice between a simple docker run and a docker compose setup depends entirely on the intended lifecycle of the wiki.
| Feature | docker run |
docker compose |
|---|---|---|
| Setup Speed | Instant | Moderate |
| Database Integration | Manual/External | Integrated/Automated |
| Persistence | Ephemeral (unless vol mounted) | Persistent (defined in YAML) |
| Configuration | Manual | Declarative |
| Use Case | Testing/Ephemeral | Production/Development |
The docker run method is akin to a quick sketch—useful for understanding the tool but insufficient for a permanent installation. In contrast, the docker compose method provides a blueprint of the entire infrastructure, ensuring that the database, networking, and configuration files are managed as a single unit.
Technical Summary and Final Analysis
The deployment of MediaWiki via Docker represents a shift from traditional LAMP (Linux, Apache, MySQL, PHP) stacks to a containerized micro-service architecture. By decoupling the application logic (MediaWiki) from the data layer (MariaDB/MySQL), the system achieves a level of portability and scalability that was previously difficult to maintain.
The critical path to success in a MediaWiki Docker deployment lies in the handling of the LocalSettings.php file. Because this file is generated dynamically during the web-based installation, the transition from a "running container" to a "configured wiki" requires a restart of the container orchestration to mount the local configuration file into the container's filesystem.
Furthermore, the modularity of the image allows for extreme customization. While the official images provide a lean starting point to minimize image size, the ability to build FROM mediawiki ensures that the software can grow to support any PHP extension required by complex plugins. Whether deploying on x86_64 or ARM64 architectures, the use of Docker ensures that the "nuclear power plant" capability of MediaWiki is harnessed within a manageable, reproducible, and scalable environment.