mwdeploy: WikiOasis MediaWiki Deployment CLI Reference

mwdeploy is the primary deployment tool for pushing MediaWiki code to all WikiOasis production servers. It runs on the staging server as the mwdeploy user and orchestrates the full pipeline: git pulls in staging, local rsync from staging to production on the staging host, optional localisation cache rebuilds, canary health checks, and a rolling deploy across every media-wiki application server — all surfaced through a live curses TUI dashboard.

Configuration

mwdeploy reads /etc/mwdeploy/config.yaml at startup. This file is rendered from the Jinja template salt/mediawiki/files/config.yaml.jinja and managed by Salt; do not edit it manually. The canonical values live in the mediawiki pillar key (see pillar/mediawiki/init.sls).

# /etc/mwdeploy/config.yaml — managed by Salt
deploy_user: mwdeploy
ssh_identity: /home/mwdeploy/.ssh/id_ed25519
staging_path: /srv/mediawiki-staging
prod_path: /srv/mediawiki
canary_vhost: test.wikioasis.org
log_file: /var/log/mwdeploy.log
haproxy_backend: mediawiki
haproxy_socket: /run/haproxy/admin.sock
backup_path: /srv/mediawiki-backup

mw_servers:
  - task-us-east-011.ovvin.wonet
  - mw-us-east-011.ovvin.wonet
  - mw-us-east-012.ovvin.wonet
  - mw-us-east-021.ovvin.wonet
  - mw-us-east-022.ovvin.wonet

proxy_servers:
  - proxy-us-east-011.ovvin.wonet
  - proxy-us-east-021.ovvin.wonet

webhooks:
  discord: ""
  slack: ""

deploy_user

OS user for SSH connections to production servers. Defaults to mwdeploy. This user must have the deploy SSH key installed.

ssh_identity

Path to the private key on the staging server used for all SSH and rsync operations. Defaults to /home/mwdeploy/.ssh/id_ed25519.

staging_path

Checkout directory on the staging server where git pulls happen. Defaults to /srv/mediawiki-staging.

prod_path

Target directory on each production server. Content is rsynced here from staging. Defaults to /srv/mediawiki.

canary_vhost

HTTP Host header sent during canary checks. Defaults to test.wikioasis.org. The check hits http://127.0.0.1/wiki/Main_Page on the target host and looks for WikiOasis content in the response body.

haproxy_backend / haproxy_socket

Backend name and stats socket path used to depool/repool servers during --rollout. Defaults to mediawiki and /run/haproxy/admin.sock.

mw_servers

Ordered list of MediaWiki application server FQDNs. Used as the default target when --servers all (or no --servers flag) is given.

proxy_servers

List of HAProxy proxy server FQDNs. Depool/repool commands are sent to every proxy in this list.

log_file

Path for the persistent deploy log. Defaults to /var/log/mwdeploy.log. Suppress with --no-log.

backup_path

Written into config.yaml by Salt from the mediawiki:backup_path pillar key. Defaults to /srv/mediawiki-backup. Present in the config file for forward compatibility; not actively read by the current mwdeploy script.

webhooks

Optional Discord and/or Slack webhook URLs. Warning-level and above messages are posted automatically. Leave empty ("") to disable.

CLI Flags

Running mwdeploy with no flags opens the TUI dashboard in read-only mode, showing the state of the last deploy from /var/log/mwdeploy-state.json. Pass at least one flag from the what to update group to trigger a new deploy.

What to Update

--core

flag

Git-pull the root of /srv/mediawiki-staging. This updates shared infrastructure files at the top level of the staging checkout. Triggers a full-tree rsync to each production server.

--mediawiki

flag

Git-pull the MediaWiki core for each resolved version under staging_path/versions/<ver>/. Use together with --versions to target a specific release, or omit --versions to default to all discovered versions.

--extension NAME

string

Git-pull a specific extension. Repeatable; also accepts comma-separated names in a single value. Only the matching extension directory is rsynced (targeted rsync), not the full tree.

mwdeploy --extension VisualEditor
mwdeploy --extension VisualEditor --extension Echo
mwdeploy --extension "VisualEditor,Echo"

--skin NAME

string

Git-pull a specific skin. Behaves identically to --extension but resolves paths under versions/<ver>/skins/. Repeatable and comma-separated.

--config

flag

Git-pull the config sub-repository at staging_path/config. Only the config/ subdirectory is rsynced to production, leaving everything else untouched.

--rsync

flag

Skip all git pulls. Rsync the current staging content to production as-is. Useful when you have manually prepared staging or want to re-push after a failed deploy without re-pulling.

--patch PATCH

string

Apply a patch file (relative to prod_path/scripts/extensions/patches/) to the staging tree before rsyncing. Repeatable. Requires --patch-target.

mwdeploy --rsync --patch fix-login.patch --patch-target extensions/PluggableAuth

--patch-target PATH

string

Directory to apply patches into, relative to staging_path/versions/<ver>/. Required when --patch is used.

Deployment Behaviour

--versions VERSION

string

MediaWiki version to target, e.g. 1.45. Use all (or omit the flag entirely) to discover and target every version directory found under staging_path/versions/.

--servers SERVERS

string

Comma-separated list of server FQDNs or short names to deploy to, or all to use the full mw_servers list from config. Defaults to all.

mwdeploy --mediawiki --servers mw-us-east-011.ovvin.wonet,mw-us-east-012.ovvin.wonet

--rollout

flag

Enable the depool/repool cycle. Before rsyncing each server, mwdeploy sends disable server mediawiki/<server> to every proxy listed in proxy_servers. After a successful canary check it sends enable server to bring the server back into rotation. Without this flag, servers stay in the HAProxy pool throughout the deploy.

--l10n

flag

Run rebuildLocalisationCache on staging after the local rsync and then again on each production server after its remote rsync. Significantly increases deploy time; use only when message or localisation files have changed.

--force

flag

Continue deploying even if a canary check fails, without prompting. Useful for emergency fixes when the site is already down. Also causes per-server failures to not abort subsequent servers.

--parallel N

integer

default:"1"

Deploy to N production servers simultaneously using a thread pool. Default is 1 (serial). Set to 2 or more for faster deploys across large fleets, at the cost of reduced blast-radius isolation.

mwdeploy --rsync --servers all --rollout --parallel 2

--provision

flag

Provision mode — rsyncs /srv/mediawiki directly to new servers that have not yet received staging content. Skips the staging preparation phase entirely. Use for bringing up new application servers.

mwdeploy --provision --servers mw-us-east-031.ovvin.wonet

--no-log

flag

Suppress file logging and webhook notifications. Output goes to the terminal only. Useful for dry-run style investigations or when you don’t want a test run recorded.

Deployment Phases

Every deploy runs through a fixed sequence of phases. The TUI dashboard tracks progress through each phase in real time.

Version and target resolution

mwdeploy resolves which MediaWiki version directories exist under staging_path/versions/ (or uses the --versions value), then resolves the target server list from --servers or the mw_servers config key. Targeted rsync paths are computed at this stage so only the affected subdirectories are synced later.

Git pulls (staging)

For each item requested (--core, --config, --mediawiki, --extension, --skin), mwdeploy runs git fetch origin followed by git reset --hard FETCH_HEAD as www-data inside the relevant path. The hard reset discards any local drift. Skipped entirely when --rsync is given.

Patch application

If --patch flags are provided, each patch file is applied with sudo -u www-data patch -p1 into the directory specified by --patch-target. Applied once per resolved version. A failure here aborts the deploy.

Local rsync (staging → prod on staging host)

The staging directory is rsynced to the production path on the staging host itself (staging_path → prod_path). Full-tree syncs use rsync -az --delete --exclude cache/. Targeted syncs (--extension, --skin, --config) rsync only the affected subdirectories, keeping the deploy fast.

L10n rebuild on staging (optional)

When --l10n is given, sudo -u www-data php scripts/mwscript.php rebuildLocalisationCache --wiki testwiki runs locally on the staging server. This ensures the cache is warm before it is pushed to production.

Canary check on staging

mwdeploy runs curl against http://127.0.0.1/wiki/Main_Page with a Host: <canary_vhost> header on the staging host and checks for an HTTP 200 response that contains WikiOasis content. Three attempts are made with a 3-second pause between each. A failure prompts for confirmation (or auto-continues with --force). A confirmed failure aborts the deploy.

Rolling deploy to production servers

For each production server (serially, or in parallel with --parallel N):

Depool — if --rollout is set, sends disable server mediawiki/<server> to every proxy via the HAProxy stats socket.
Rsync — pushes the prepared prod_path content from staging to the server using rsync --rsync-path="sudo rsync" --chown=www-data:mediawiki-admins.
L10n — if --l10n is set, runs rebuildLocalisationCache on the production server over SSH.
Canary — repeats the HTTP canary check on the production server.
Repool — if --rollout is set and canary passes, sends enable server to bring the server back into rotation.

TUI Dashboard

The curses dashboard opens automatically whenever a deploy is running. Run mwdeploy with no flags to reopen it in read-only mode against the last saved state in /var/log/mwdeploy-state.json. The dashboard is divided into three sections: Preparation — tracks the staging phases (git pulls, local rsync, l10n, canary). Shows a live progress bar, step name, and the last few log lines. Servers — one row per production server showing name, status icon, elapsed time, a step progress bar (while running), and recent log lines. Summary — once all servers are terminal, shows counts of succeeded, failed, and skipped/rolled-back servers. Any failed servers are listed with their last log line in an Issues section.

Status States

Icon	State	Meaning
`○ pending`	`pending`	Waiting; the server has not started yet
`⟳ running`	`running`	Actively deploying
`✓ done`	`done`	All steps completed successfully
`✗ failed`	`failed`	A step failed (rsync, l10n, or canary)
`⤺ rolled back`	`rolled_back`	Repooled after a detected failure
`– skipped`	`skipped`	Deploy was aborted by an earlier failure; server was not touched

Keyboard Shortcuts

Key	Action
`↑` / `↓`	Move selection between servers
`Ctrl+O`	Open detail log view for selected server
`Ctrl+R`	Open depool/repool menu for selected server
`Q` / `Esc`	Back (in detail view)
`Ctrl+X`	Exit dashboard

Canary Prompt Overlay

When a canary check fails and --force is not set, the dashboard freezes and displays a prompt overlay:

  Canary failed on mw-us-east-012 (HTTP 502). Continue?

  [Y]  Yes, continue
  [N]  Stop here

Press Y to continue to the next server or N to abort the remaining deploy.

Manual HAProxy Control

Press Ctrl+R on a selected server to open the HAProxy pool action menu while a deploy is in progress. This lets you manually depool or repool a server independent of the automated --rollout cycle:

  HAProxy pool action for mw-us-east-012:

  [D]  Depool (disable server)
  [R]  Repool (enable server)
  [N]  Cancel

Usage Examples

# Full deploy: pull core, all MediaWiki versions, rebuild l10n, deploy to all servers
mwdeploy --core --mediawiki --l10n --servers all --rollout

# Deploy a single extension across all versions
mwdeploy --extension VisualEditor --servers all --rollout

# Deploy config only
mwdeploy --config --servers all --rollout

# Deploy to two specific servers only, rolling out through HAProxy
mwdeploy --mediawiki --servers mw-us-east-011.ovvin.wonet,mw-us-east-012.ovvin.wonet --rollout

# Rsync only — push current staging content without any git pulls
mwdeploy --rsync --servers all --rollout

# Parallel deploy with 2 workers at a time
mwdeploy --rsync --servers all --rollout --parallel 2

# Provision a brand-new server (no staging sync, copies prod directly)
mwdeploy --provision --servers mw-us-east-031.ovvin.wonet

# Apply a patch to an extension then rsync
mwdeploy --rsync \
  --patch fix-login.patch \
  --patch-target extensions/PluggableAuth \
  --servers all --rollout

mwdeploy always runs as the mwdeploy user on the staging server. SSH connections to production servers use the key at ssh_identity with SSH ControlMaster multiplexing (60-second persist) to amortise connection overhead across the rolling deploy.

Logging and Webhooks

Deploy events are written to log_file (default /var/log/mwdeploy.log) in the format:

2025-01-15T14:32:10Z [INFO] mwdeploy starting — targets: ['mw-us-east-011.ovvin.wonet', ...]
2025-01-15T14:32:11Z [INFO] git pull  core
2025-01-15T14:32:45Z [INFO] Local rsync  /srv/mediawiki-staging → /srv/mediawiki

Warning-level and higher messages are also POSTed to the webhooks.discord and/or webhooks.slack URLs configured in config.yaml. The deploy start and completion (or failure) notifications are always sent regardless of log level, giving teams a lightweight notification channel without requiring full log tailing. Suppress all file and webhook output with --no-log for one-off or test runs.

Deployment

Salt Modules

Runbooks

mwdeploy: WikiOasis MediaWiki Deployment CLI Reference

Configuration

deploy_user

ssh_identity

staging_path

prod_path

canary_vhost

haproxy_backend / haproxy_socket

mw_servers

proxy_servers

log_file

backup_path

webhooks

CLI Flags

What to Update

Deployment Behaviour

Deployment Phases

TUI Dashboard

Status States

Keyboard Shortcuts

Canary Prompt Overlay

Manual HAProxy Control

Usage Examples

Logging and Webhooks

Build docs developers (and LLMs) love

Deployment

Salt Modules

Runbooks

Documentation Index

​Configuration

deploy_user

ssh_identity

staging_path

prod_path

canary_vhost

haproxy_backend / haproxy_socket

mw_servers

proxy_servers

log_file

backup_path

webhooks

​CLI Flags

​What to Update

​Deployment Behaviour

​Deployment Phases

​TUI Dashboard

​Status States

​Keyboard Shortcuts

​Canary Prompt Overlay

​Manual HAProxy Control

​Usage Examples

​Logging and Webhooks

Build docs developers (and LLMs) love

Configuration

CLI Flags

What to Update

Deployment Behaviour

Deployment Phases

TUI Dashboard

Status States

Keyboard Shortcuts

Canary Prompt Overlay

Manual HAProxy Control

Usage Examples

Logging and Webhooks