MediaWiki Setup Guide

Reference used: Official MediaWiki Docker Image on Docker Hub (Docker + MariaDB)

1. Overview

This guide explains how to deploy and configure MediaWiki using Docker Compose (or Portainer), with persistent storage and a MariaDB database. The example setup exposes MediaWiki on port 8191 and uses the datecode prefix 251029 for all volumes.

Once configured, the installation will persist even after relaunching containers since all data and uploads are stored in Docker volumes.

2. Folder Setup

Create a dedicated folder for your stack on the Docker host (example for PC03). Note the path uses stacks (not stacs):

sudo mkdir -p /opt/stacks/mediawiki
cd /opt/stacks/mediawiki

If you are using Portainer (Web editor), you can still keep files here and reference them as bind mounts.

3. Stack YAML (works in Portainer or docker compose)

Use this YAML either in Portainer → Stacks → Add stack (Web editor) or as a local docker-compose.yml if you prefer CLI later.

services:
  mediawiki:
    image: mediawiki
    container_name: mediawiki
    restart: always
    ports:
      - 8191:80
    depends_on:
      - database
    volumes:
      - 251029_images:/var/www/html/images
      # After initial setup, place LocalSettings.php on the host at
      # /opt/stacks/mediawiki/LocalSettings.php and uncomment the next line:
      # - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

  database:
    image: mariadb
    container_name: mediawiki-db
    restart: always
    environment:
      MYSQL_DATABASE: wiki
      MYSQL_USER: wiki
      MYSQL_PASSWORD: wiki
      MYSQL_ROOT_PASSWORD: wiki
    volumes:
      - 251029_db:/var/lib/mysql

volumes:
  251029_images:
  251029_db:

If using Portainer, paste this in the stack Web editor and click Deploy the stack.

4. First-Time Setup Wizard

After containers start successfully:

Open your browser and go to http://localhost:8191 (or use your host IP if remote).
Choose your language and click Continue.
Environment Check – MediaWiki will verify PHP and required extensions.
Connect to Database:
- Database Type: MySQL / MariaDB
- Database Host: database
- Database Name: wiki
- Database Table Prefix (no hyphens): (leave blank) — only used if running multiple wikis in one database.
- Database User: wiki
- Database Password: wiki
- Connect over SSL: Leave unchecked. (Your DB runs locally in Docker, SSL is not needed.)
Database Settings – Leave defaults (uses my_wiki schema).
Name your Wiki – Enter a site name and create your admin account.
Continue until the “Download LocalSettings.php” step.

5. Applying LocalSettings.php (Portainer step-by-step)

Goal: Mount the generated LocalSettings.php into the container at /var/www/html/LocalSettings.php using an absolute host path (required by Portainer).

Copy the file to the host path

sudo cp /home/user/Downloads/LocalSettings.php /opt/stacks/mediawiki/
sudo chmod 644 /opt/stacks/mediawiki/LocalSettings.php

Edit the Portainer stack YAML

Portainer → Stacks → your MediaWiki stack → Editor
Under mediawiki.volumes, uncomment or add this bind mount line (absolute path):

- /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

Click Update the stack (or Deploy the stack if first time).

Verify the file is mounted inside the container

docker exec -it mediawiki ls -l /var/www/html/LocalSettings.php

If you see the file listed, reload the wiki page.
If not listed, re-check step 2 for typos or indentation and update the stack again.

(If the page still errors)

Confirm the filename is exact (case-sensitive): LocalSettings.php (not .txt).
Convert Windows line endings just in case:

sudo apt-get update && sudo apt-get install -y dos2unix
sudo dos2unix /opt/stacks/mediawiki/LocalSettings.php

Re-update the stack.

Note: With Portainer, you can change DB passwords in the stack env vars and Update the stack later — your data persists in named volumes 251029_db and 251029_images.

6. Optional Enhancements

Backups: docker exec -i mediawiki-db mysqldump -uwiki -pwiki wiki > backup.sql docker run --rm -v 251029_images:/data -v "$PWD":/backup alpine tar -czf /backup/images.tgz -C /data .
Extensions & Skins: Mount local directories for version-controlled assets: - ./extensions:/var/www/html/extensions - ./skins:/var/www/html/skins
Inspect Volumes: docker volume inspect 251029_images docker volume inspect 251029_db

7. Common Maintenance Actions

Quick Portainer bind-mount recap

Relative paths like ./LocalSettings.php do not work in Portainer bind mounts.
Always use the absolute host path: /opt/stacks/mediawiki/LocalSettings.php.

Via Portainer (UI)

Restart stack: Stacks → MediaWiki → Recreate/Update.
Edit YAML & redeploy: Stacks → MediaWiki → Editor → Update the stack.
Container logs: Containers → select container → Logs.

Via CLI (optional)

Action	Command
Stop containers	`docker compose down`
Relaunch containers (after edit)	`docker compose up -d`
View logs	`docker compose logs -f`
Check running containers	`docker ps`

Via Portainer (UI)

Restart stack: Stacks → MediaWiki → Recreate/Update.
Edit YAML & redeploy: Stacks → MediaWiki → Editor → Update the stack.
Container logs: Containers → select container → Logs.

Via CLI (optional)

Action	Command
Stop containers	`docker compose down`
Relaunch containers (after edit)	`docker compose up -d`
View logs	`docker compose logs -f`
Check running containers	`docker ps`

8. Notes for Portainer Users

If using Portainer, simply import the same YAML as a stack.
To update passwords or config, edit environment variables under the database service and redeploy the stack.
Volumes (251029_images and 251029_db) retain data between restarts, so you can safely relaunch or reconfigure without losing content.

9. MediaWiki Extensions

Video Reference: MediaWiki Extensions Tutorial (YouTube)

Helpful Extension References

These resources provide detailed guidance on installing, enabling, and maintaining common MediaWiki extensions used in production and Wikimedia environments.

Game in the Brain