View source for MediaWiki Setup Guide Portainer-Docker-251215-00


= MediaWiki Setup Guide (Portainer & Docker) =
This guide documents how to deploy, configure, and secure a '''MediaWiki''' instance using '''Portainer''' and '''Docker Compose'''. Designed as a general tutorial for any user, it walks through the process of setting up a wiki from scratch. It covers initial deployment, resolving common extension folder issues, and applying production configurations (using <code>wiki.gi7b.org</code> as the example domain).

'''Reference:''' Official MediaWiki Docker Image https://hub.docker.com/_/mediawiki 

== 1. Prerequisites ==
Before starting, ensure you have:

1. Docker & Docker Compose

    Installation (Linux/Windows/Mac): <nowiki>https://docs.docker.com/engine/install/</nowiki>

    Docker Compose Standalone (if needed separately): <nowiki>https://docs.docker.com/compose/install/</nowiki>

2. Portainer CE (Community Edition)

    Docker Standalone Install Guide: <nowiki>https://docs.portainer.io/start/install-ce/server/docker/linux</nowiki>

3. Domain & Cloudflare Setup

    How to Register a Domain with Cloudflare: <nowiki>https://developers.cloudflare.com/registrar/get-started/register-domain/</nowiki>

    Cloudflare Tunnel (Cloudflared) Setup Guide: <nowiki>https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/</nowiki>

4. NGINX Reverse Proxy

    Nginx Proxy Manager (Docker Setup): <nowiki>https://nginxproxymanager.com/guide/#quick-setup</nowiki> (This is the standard GUI-based Nginx used in Docker stacks)

    Nginx Official Docker Image (for raw configuration): <nowiki>https://hub.docker.com/_/nginx</nowiki>

== 2. Host Folder Setup ==
Create a dedicated folder for your stack on the '''Docker host'''. This path is critical as it will store your configuration and extensions.
 # Run on host terminal 
 sudo mkdir -p /opt/stacks/mediawiki
 sudo mkdir -p /opt/stacks/mediawiki/extensions
 cd /opt/stacks/mediawiki

== 3. Deployment (Portainer / Docker Compose) ==
Use the following YAML configuration.

=== In Portainer: ===

# Go to '''Stacks''' → '''Add stack'''.
# Name it mediawiki.
# Paste the configuration below into the Web editor.
# Click '''Deploy the stack'''.

=== docker-compose.yml ===
 <services:
   mediawiki:
     image: mediawiki
     container_name: mediawiki
     restart: always
     ports:
       - 8595:80
     depends_on:
       - database
     volumes:
       - 230912_images:/var/www/html/images
       # EXTENSIONS: Mounts host folder to container (Requires "Magic Command" step below)
       - /opt/stacks/mediawiki/extensions:/var/www/html/extensions
       # CONFIG: Uncomment the line below AFTER generating LocalSettings.php
       # - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro
 
   database:
     image: mariadb
     container_name: mediawiki-db
     restart: always
     environment:
       MYSQL_DATABASE: mediawiki
       MYSQL_USER: mediawiki
       MYSQL_PASSWORD: mediawiki
       MYSQL_ROOT_PASSWORD: mediawiki
     volumes:
       - 230912_db:/var/lib/mysql
 
 volumes:
   230912_images:
   230912_db:</code>

== 4. First-Time Setup Wizard ==

# Open '''<nowiki>http://localhost:8191</nowiki>''' (or your server IP:8191).
# Follow the prompts. When asked for '''Database Settings''', use:

* '''Host:''' database
* '''Name:''' mediawiki
* '''User:''' mediawiki
* '''Password:''' mediawiki

# Complete the wizard and '''Download LocalSettings.php''' to your computer.

== 5. Fixing Extensions (The "Magic Command") ==
'''Crucial Step:''' Because we mounted a volume to /extensions, the container's default extensions (VisualEditor, WikiEditor, etc.) are hidden. We must copy them from the image to the host.

'''Run this on your Host Terminal:'''
 docker run --rm --entrypoint tar mediawiki -c -C /var/www/html/extensions . | tar -x -C /opt/stacks/mediawiki/extensions
'''Download Mermaid (External Extension):'''
 <code>cd /opt/stacks/mediawiki/extensions
 git clone <nowiki>[https://github.com/SemanticMediaWiki/Mermaid.git]</nowiki>(<nowiki>https://github.com/SemanticMediaWiki/Mermaid.git</nowiki>) Mermaid</code>
Verify the folder content: You should see a mix of default extensions and Mermaid:

ls -F /opt/stacks/mediawiki/extensions/

''Output should look like this:''
 <code>AbuseFilter/    CiteThisPage/      Echo/         Interwiki/      Mermaid/          PageImages/        README          SpamBlacklist/          TextExtracts/       WikiEditor/
 CategoryTree/   CodeEditor/      Gadgets/    Linter/      MultimediaViewer/  ParserFunctions/  ReplaceText/      SyntaxHighlight_GeSHi/  Thanks/
 CheckUser/      ConfirmEdit/      ImageMap/   LoginNotify/  Nuke/              PdfHandler/        Scribunto/      TemplateData/          TitleBlacklist/
 Cite/            DiscussionTools/  InputBox/   Math/       OATHAuth/          Poem/            SecureLinkFixer/  TemplateStyles/      VisualEditor/</code>

== 6. Configuring LocalSettings.php ==
Move the downloaded LocalSettings.php to /opt/stacks/mediawiki/LocalSettings.php.
 # in linux terminal
 sudo nano /opt/stacks/mediawiki/LocalSettings.php
Edit the file (sudo nano /opt/stacks/mediawiki/LocalSettings.php) and make the following changes:

=== A. Set the Custom Domain ===
Find the $wgServer line (around line 30) and change it to your actual domain:
 ## The protocol and server name to use in fully-qualified URLs 
 $wgServer = "<nowiki>https://wiki.gi7b.org</nowiki>";

=== B. Add Permissions & Extensions ===
Paste this block at the '''very bottom''' of the file to enable security and extensions.
 <code># -----------------------------------------------------------------------
 # CUSTOM PERMISSIONS & EXTENSIONS
 # -----------------------------------------------------------------------
 
 # 1. SECURITY: Prevent anonymous editing and account creation
 $wgGroupPermissions['*']['edit'] = false;
 $wgGroupPermissions['*']['createaccount'] = false;
 
 # 2. BUNDLED EXTENSIONS (Included in Docker image)
 wfLoadExtension( 'WikiEditor' );
 wfLoadExtension( 'VisualEditor' );
 wfLoadExtension( 'CodeEditor' );
 wfLoadExtension( 'SyntaxHighlight_GeSHi' );
 wfLoadExtension( 'Cite' );
 wfLoadExtension( 'InputBox' );
 wfLoadExtension( 'Scribunto' );
 wfLoadExtension( 'AbuseFilter' );
 wfLoadExtension( 'Gadgets' );
 wfLoadExtension( 'ParserFunctions' );
 wfLoadExtension( 'Interwiki' );
 
 # 3. EXTERNAL EXTENSIONS (Must be manually downloaded to /extensions folder)
 wfLoadExtension( 'Mermaid' );
 
 # 4. VISUALEDITOR CONFIGURATION
 # Enable by default for everyone
 $wgDefaultUserOptions['visualeditor-enable'] = 1;
 # Allow VE to work in Docker containers (Fixes "Error contacting Parsoid")
 $wgVisualEditorParsoidForwardCookies = true;
 
 # 5. LUA CONFIGURATION (Required for Scribunto)
 $wgScribuntoDefaultEngine = 'luastandalone';</code>

== 7. Apply Changes ==

# '''Mount the settings:''' In Portainer, go to the Stack Editor and '''uncomment''' the LocalSettings.php line.
# '''Update the Stack:''' Click "Update the stack".
# '''Run Database Update:''' Run this command to initialize tables for the new extensions:  docker exec -it mediawiki php maintenance/update.php --quick

Your wiki is now live at '''<nowiki>https://wiki.gi7b.org</nowiki>''' with VisualEditor and Mermaid enabled!

== 8. Email Configuration and Admin Set up ==
----

=== 1. Email goal (what we were trying to achieve) ===
* MediaWiki must be able to '''send email reliably'''
** account confirmation
** password reset
** notifications
* Emails should appear as coming from '''<code>info@gi7b.org</code>'''
* Authentication must work with '''Gmail / Google Workspace'''
* No local SMTP server, no Docker mail container

Success criterion (important to remember):<blockquote>MediaWiki explicitly says '''“email sent”''' — not just “no error”.</blockquote>
----

=== 2. App Password (Google side) ===

=== Where it lives ===

* '''Google Account settings''', not Gmail UI   <nowiki>https://myaccount.google.com</nowiki>

* → Security → App passwords

=== Preconditions ===

* 2-Step Verification '''must be enabled'''
* App type: '''Mail'''
* Device: '''Other''' (e.g. <code>MediaWiki wiki.gi7b.org</code>)

=== Critical detail (easy to miss, caused real failure) ===
Google shows the password like this:

But MediaWiki / PHP '''must receive it without spaces''':

If you keep the spaces:

* Google returns <code>SMTP 535 5.7.8 BadCredentials</code>
* MediaWiki misleadingly says “invalid characters”

'''This was one of the key fixes.'''
----

=== 3. Real email vs alias (authentication reality) ===

=== Core rule (non-negotiable) ===
<blockquote>'''SMTP login must use a real mailbox, not an alias.'''</blockquote>Examples:
{| class="wikitable"
!Address type
!Can authenticate?
|-
|Real Gmail / Workspace mailbox
|✅ Yes
|-
|Alias (Send mail as)
|❌ No
|-
|Forward-only address
|❌ No
|}
So:

* '''Login / username''' → real mailbox (e.g. <code>admin@gi7b.org</code>, <code>justin@gi7b.org</code>)
* '''Sender address''' → can be <code>info@gi7b.org</code>

This is how Google enforces auditability and DMARC integrity.
----

=== 4. “Send as” using Cloudflare Email Routing (alias setup) ===
Your <code>info@gi7b.org</code> address was '''not''' a real mailbox.

It was configured as an alias using '''Cloudflare Email Routing'''.

That’s fine — and correct — for sending.

Reference (as requested, naked link only):

https://www.cloudflare.com/developer-platform/products/email-routing/

Key idea:

* Cloudflare routes mail for <code>info@gi7b.org</code>
* Gmail authenticates as the '''real mailbox'''
* MediaWiki sends “from” the alias

This combination is valid and common.
----

=== 5. Final MediaWiki SMTP configuration (conceptual) ===
 $wgEnableEmail = true;
 $wgEnableUserEmail = true;
 $wgSMTP = [
   'host'     => 'ssl://smtp.gmail.com',
   'IDHost'   => 'wiki.gi7b.org',
   'port'     => 465,
   'auth'     => true,
   'username' => 'admin@gi7b.org',   // REAL mailbox
   'password' => 'APP_PASSWORD_OF_ADMIN',
 ];
 $wgPasswordSender = 'info@gi7b.org'; // ALIAS is fine here
 
What mattered conceptually (not copying exact secrets):

* <code>username</code> = '''real mailbox'''
* <code>password</code> = '''App Password, no spaces'''
* <code>wgPasswordSender</code> = alias (<code>info@gi7b.org</code>)
* SMTP host = <code>smtp.gmail.com</code>
* TLS/SSL enabled

Once all three conditions were true:

# real mailbox for login
# app password without spaces
# alias only used for sending

→ Google accepted authentication.
----

=== 6. Testing and defining “success” ===

=== What failed before ===

* Account confirmation attempted
* Gmail rejected auth
* MediaWiki showed:

=== What changed after fixes ===

* Retried account confirmation
* MediaWiki returned:<blockquote>'''“email sent”'''</blockquote>

=== This is the success criterion ===
Not:

* “no error”
* “page didn’t crash”

But explicitly:<blockquote>'''MediaWiki confirms the email was sent'''</blockquote>That tells you:

* SMTP auth works
* Mailer pipeline is functional
* Future account/password flows will work

----

=== 7. Final step: making your account admin ===
Once email was stable, we finalized control.

=== What we did ===

* Used the MediaWiki maintenance runner
* Promoted your existing account
* Forced promotion because the user already existed

Command (conceptually):

* promote <code>justinaquino</code>
* assign <code>sysop</code> + <code>bureaucrat</code>
* confirmed by:

=== Important nuance ===

* Some helper scripts (<code>showUserRights</code>, <code>version</code>) are missing in newer MediaWiki builds
* That '''does not invalidate''' the promotion
* UI verification (<code>Special:UserRights</code>, <code>Special:CreateAccount</code>) is canonical

----

=== 8. Final mental model (so this sticks) ===
* '''Email'''
** Gmail = SMTP server
** MediaWiki = SMTP client
** App Password = machine credential
** Alias ≠ login identity
* '''Security'''
** Real mailbox authenticates
** Alias is presentation only
** Cloudflare handles routing, not auth
* '''Success'''
** “Email sent” is the only signal that matters
** Admin rights are confirmed via UI, not missing CLI helpers

== 9. Protect your account from brute force (real defenses) ==
MediaWiki already has '''some protection''', but we’ll harden it properly.

=== Layer 1 — Enable built-in throttling (do this) ===
Add to <code>LocalSettings.php</code>:
 # Login attempt throttling
 $wgRateLimits['user']['login'] = [ 5, 60 ];   // 5 attempts per minute
 $wgRateLimits['ip']['login']   = [ 20, 300 ]; // 20 attempts per 5 minutes
This alone stops most brute-force scripts.

== 10. List of Extensions ==
[https://www.youtube.com/watch?v=4xYbqbabTwI Youtube: Introduction to MediaWiki: Wikipedia's extensions (Part 2)]
# '''[[wikipedia:Special:Version|The installed Extensions of Wikipedia]]'''
#