computer-playbook/roles/web-app-mediawiki/README.md

MediaWiki

Description

Empower your knowledge base with MediaWiki, a versatile and collaborative platform designed to build comprehensive, user-driven documentation. MediaWiki offers a rich extension ecosystem, robust content management capabilities, and customizable configurations to transform your information into a vibrant, living resource.

Overview

This role deploys MediaWiki using Docker, automating the setup of your wiki instance along with its underlying MariaDB database. It handles generating the essential configuration file (LocalSettings.php) from a seeded template and integrates with an NGINX reverse proxy for secure, efficient web access.

Cosmos

The diagram places MediaWiki in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

flowchart LR
    subgraph deps [Dependencies]
        dep_svc_ai_litellm["svc-ai-litellm 🐳🐝"]
        dep_svc_bkp_volume_2_local["svc-bkp-volume-2-local 💻"]
        dep_svc_db_mariadb["svc-db-mariadb 🐳🐝"]
        dep_svc_net_tor["svc-net-tor 🐳🐝"]
        dep_web_app_dashboard["web-app-dashboard 🐳🐝"]
        dep_web_app_keycloak["web-app-keycloak 🐳🐝"]
        dep_web_app_matomo["web-app-matomo 🐳🐝"]
        dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
        dep_web_app_stalwart["web-app-stalwart 🐳🐝"]
        dep_web_svc_css["web-svc-css 💻"]
        dep_web_svc_logout["web-svc-logout 🐳🐝"]
    end
    subgraph role [web-app-mediawiki 🐳🐝]
        svc_litellm["litellm"]
        svc_sso["sso"]
        svc_logout["logout"]
        svc_dashboard["dashboard"]
        svc_matomo["matomo"]
        svc_email["email"]
        svc_mariadb["mariadb"]
        svc_mediawiki["mediawiki"]
        svc_css["css"]
        svc_prometheus["prometheus"]
        svc_tor["tor"]
        svc_container_backup["container_backup"]
    end
    dep_svc_ai_litellm -. "0..1" .-> svc_litellm
    dep_svc_bkp_volume_2_local -. "0..1" .-> svc_container_backup
    dep_svc_db_mariadb -. "0..1" .-> svc_mariadb
    dep_svc_net_tor -. "0..1" .-> svc_tor
    dep_web_app_dashboard -. "0..1" .-> svc_dashboard
    dep_web_app_keycloak -. "0..1" .-> svc_sso
    dep_web_app_matomo -. "0..1" .-> svc_matomo
    dep_web_app_prometheus -. "0..1" .-> svc_prometheus
    dep_web_app_stalwart -. "0..1" .-> svc_email
    dep_web_svc_css -. "0..1" .-> svc_css
    dep_web_svc_logout -. "0..1" .-> svc_logout

Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.

Features

• Collaborative Editing: Enable multiple users to create and update content simultaneously through an intuitive interface.
• Extensible Architecture: Leverage a wide range of extensions and customization options to tailor the wiki experience to your needs.
• Robust Content Management: Organize, categorize, and retrieve information efficiently with powerful content management tools.
• Scalable Deployment: Utilize Docker for a portable and scalable setup that adapts as your community grows.
• Secure and Reliable: Benefit from secure access via an NGINX reverse proxy combined with a MariaDB backend for reliable data storage.

Quick Setup

Development

Clone, set up the workstation, and deploy MediaWiki onto the local stack:

git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-app-mediawiki full_cycle=false

Production

Run the published image to provision the inventory and deploy MediaWiki to a managed server (the mounted volume persists the inventory):

APP=web-app-mediawiki
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"

docker run --rm -it \
  -v "$PWD/inventories:/etc/infinito.nexus/inventories" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      --diff -vv'

Addons

This role ships its OIDC login stack and its AI editing stack as unified addons declared in meta/addons/. All four are MediaWiki extensions installed from upstream at the REL<major>_<minor> branch matching the pinned image, and each is gated on a service flag. Secrets are rendered through the role's templates and never inlined into an addon declaration.

Addon	Mechanism	Default state	Bridges
PluggableAuth	extension	enabled when services.sso.enabled	none
OpenIDConnect	extension	enabled when services.sso.enabled	sso
VisualEditorPlus	extension	enabled when services.litellm.enabled	litellm
AIEditingAssistant	extension	enabled when services.litellm.enabled	litellm

meta/addons/ is also the download list: MEDIAWIKI_EXT_NAMES keeps only the addons whose enabled resolves true, so a deployment without the matching service never pulls that tarball or runs composer for it.

AI editing assistant

With services.litellm.enabled, templates/LocalSettings.php.j2 loads VisualEditor (bundled in the image), VisualEditorPlus and AIEditingAssistant, then points the extension's open-ai provider at the in-cluster gateway:

• $wgAIEditingAssistantActiveProvider is open-ai.
• $wgAIEditingAssistantActiveProviderConnection is the JSON object {url, endpoint, model, secret} built from MEDIAWIKI_LITELLM_CONNECTION; url is LITELLM_OPENAI_BASE_LOCAL_URL and secret is this role's own credentials.litellm_api_key. The braces are mandatory: a brace-free value is re-wrapped as {"legacy": ...} upstream and the provider falls back to the vendor endpoint at api.openai.com.
• $wgHTTPTimeout is raised inside the same block because core's 25s is below a cold local model's first token.

The wiring block sits behind a file_exists guard on extensions/VisualEditorPlus/vendor/autoload.php, because LocalSettings.php is rendered before the extensions are installed and VisualEditorPlus fatals until its composer step has run.

tasks/utils/ai_gateway.yml runs after update.php. It includes the shared gateway consumer contract, then reads both globals back out of the running container with maintenance/run.php getConfiguration --format=json and asserts the provider, the base URL and the model, so an unconfigured surface cannot reach a green deploy.

Further Resources

• MediaWiki Official Website
• MediaWiki Documentation

Swarm + NFS pilot

Volume layout under DEPLOYMENT_MODE: swarm with storage.backend: nfs:

• images/ opts into NFS (nfs: true in the compose_volumes call from templates/compose.yml.j2). The volume is shared across all swarm nodes so the MediaWiki application service can be rescheduled freely.
• extensions/ stays local. Extensions are rebuilt from the role-managed git source on every install — no shared state needs to survive a node move.
• MariaDB data stays local on the manager node via svc-db-mariadb pinning. NFS for the DB data directory is intentionally out of scope for v1 (locking / fsync semantics). See 023's Future Extensions.

CI gate: .github/workflows/call-test-deploy.yml provisions a 3-node DinD swarm, deploys this role as a stack, drains the worker running the application service, and asserts that wiki content survives the reschedule.

Persona contract opt-outs

This role declares PERSONA_ADMINISTRATOR_BLOCKED and PERSONA_BIBER_BLOCKED in templates/playwright.env.j2 for two different reasons. The wiki's bureaucrat and sysop is a local account created by maintenance/run.php createAndPromote in tasks/04_admin.yml with MEDIAWIKI_ADMINISTRATOR_PASSWORD — the role-local credentials.administrator_password, not the Keycloak secret the persona helper carries in ADMIN_PASSWORD. $wgPluggableAuth_EnableLocalLogin is false, so no native form accepts that password anyway, and $wgOpenIDConnect_UseEmailNameAsUserName lands the Keycloak identity on a separate, e-mail-named wiki account that holds no sysop rights.

Biber is blocked by $wgPluggableAuth_EnableAutoLogin, which this role sets to true in vars/main.yml: every anonymous request is bounced straight back into the identity provider, so the verified unauthenticated landing after in-app logout that the persona contract demands can never be observed here. The path back to the generic personas is either auto-login off, or a deploy step that promotes the OIDC-provisioned administrator account to sysop.

Credits

Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).