Editing Wiki.tetrain.com Runbook (section)

== Phase 3 — Docker-based version-hop chain (verified exact — reconstructed from live Docker images) ==

'''Why Docker per-hop''': the hop chain needs 5 different PHP runtimes (5.6 → 7.2 → 7.4 → 8.0 → 8.1) that can't coexist natively on one Rocky 9 box. Each hop is a disposable container built from the official <code><nowiki>php</nowiki></code> Docker Hub image (which retains every historical tag) plus the matching MediaWiki release tarball downloaded directly from <code><nowiki>releases.wikimedia.org</nowiki></code>.

=== 3.1 Download the 6 release tarballs ===

<pre>
<nowiki>
cd /root/mw-hop-migration
mkdir -p tarballs && cd tarballs
for v in 1.23.16 1.27.7 1.31.16 1.35.13 1.39.11 1.43.2; do
  curl -O "https://releases.wikimedia.org/mediawiki/${v%.*}/mediawiki-${v}.tar.gz"
done
# 1.43.2 was later replaced with 1.43.9 (see 3.5) — its pinned Composer deps hit a security
# advisory block; 1.43.9 resolved cleanly:
curl -O "https://releases.wikimedia.org/mediawiki/1.43/mediawiki-1.43.9.tar.gz"
</nowiki>
</pre>

(All 7 tarballs — including the superseded 1.43.2 — are still on disk at <code><nowiki>/root/mw-hop-migration/tarballs/</nowiki></code>.)

=== 3.2 Shared MariaDB container (persists across every hop) ===

<pre>
<nowiki>
docker network create mwmigrate

mkdir -p /root/mw-hop-migration/db-data
docker run -d --name mw-mariadb \
  --network mwmigrate \
  -e MARIADB_ROOT_PASSWORD=migrate_temp_pw \
  -v /root/mw-hop-migration/db-data:/var/lib/mysql \
  mariadb:10.11
</nowiki>
</pre>

(Verified live — this exact container is still running, <code><nowiki>docker inspect mw-mariadb</nowiki></code> confirms the env var, mount, and network above.)

Load the source dump into it:

<pre>
<nowiki>
docker exec -i mw-mariadb mariadb -uroot -pmigrate_temp_pw -e "CREATE DATABASE my_wiki;"
docker exec -i mw-mariadb mariadb -uroot -pmigrate_temp_pw my_wiki < /root/mw-hop-migration/my_wiki_source.sql
</nowiki>
</pre>

=== 3.3 Per-hop Dockerfile (shared template, confirmed exact via <code><nowiki>docker history --no-trunc</nowiki></code>) ===

One template, parameterized by PHP tag:

<pre>
<nowiki>
# Dockerfile.template
ARG PHP_TAG
FROM php:${PHP_TAG}
RUN apt-get update && apt-get install -y --no-install-recommends \
    libicu-dev libpng-dev libjpeg-dev libxml2-dev libonig-dev zlib1g-dev \
    && docker-php-ext-configure gd --with-jpeg 2>/dev/null || docker-php-ext-configure gd 2>/dev/null || true \
    && docker-php-ext-install mysqli intl gd mbstring calendar opcache 2>&1 | tail -20 \
    && rm -rf /var/lib/apt/lists/*
</nowiki>
</pre>

(This is the literal, byte-for-byte content still on disk at <code><nowiki>/root/mw-hop-migration/hops/Dockerfile.template</nowiki></code>; the <code><nowiki>RUN</nowiki></code> line matches exactly what <code><nowiki>docker history --no-trunc mw-hop1-1.23:latest</nowiki></code> shows as that image's top custom layer.)

PHP tag per hop (confirmed by running <code><nowiki>php -v</nowiki></code> inside each surviving image):

{| class="wikitable"
|-
! Hop !! MediaWiki !! PHP tag !! Confirmed running <code><nowiki>php -v</nowiki></code>
|-
| 1 || 1.23.16 || <code><nowiki>php:5.6-apache</nowiki></code> || PHP 5.6.40
|-
| 2 || 1.27.7 || <code><nowiki>php:5.6-apache</nowiki></code> || PHP 5.6.40
|-
| 3 || 1.31.16 || <code><nowiki>php:7.2-apache</nowiki></code> || PHP 7.2.34
|-
| 4 || 1.35.13 || <code><nowiki>php:7.4-apache</nowiki></code> || PHP 7.4.33
|-
| 5 || 1.39.11 || <code><nowiki>php:8.0-apache</nowiki></code> || PHP 8.0.30
|-
| 6 || 1.43.9 || <code><nowiki>php:8.1-apache</nowiki></code> || PHP 8.1.34
|}

Build each image (repeat per row above):

<pre>
<nowiki>
cd /root/mw-hop-migration/hops
mkdir -p hop1-1.23 && cd hop1-1.23
tar xzf ../../tarballs/mediawiki-1.23.16.tar.gz --strip-components=1 -C . --one-top-level=src 2>/dev/null \
  || (mkdir -p src && tar xzf ../../tarballs/mediawiki-1.23.16.tar.gz --strip-components=1 -C src)
cp ../Dockerfile.template Dockerfile
docker build --build-arg PHP_TAG=5.6-apache -t mw-hop1-1.23:latest .
cd ..
</nowiki>
</pre>

Repeat for hop2 (<code><nowiki>5.6-apache</nowiki></code>), hop3 (<code><nowiki>7.2-apache</nowiki></code>), hop4 (<code><nowiki>7.4-apache</nowiki></code>), hop5 (<code><nowiki>8.0-apache</nowiki></code>), hop6 (<code><nowiki>8.1-apache</nowiki></code>), substituting the tarball, directory name, and <code><nowiki>PHP_TAG</nowiki></code> each time.

'''Verify''': <code><nowiki>docker images</nowiki></code> should list all 6 (still true on the live box today, ~700-850MB each).

=== 3.4 Run each hop — copy source in, point at shared DB, run <code><nowiki>update.php</nowiki></code> ===

For each hop, in order (1→2→3→4→5→6), with the *previous* hop's DB state already loaded:

<pre>
<nowiki>
# Example shown for hop 1; same shape for hops 2-6, just swap the image/paths.
docker run --rm \
  --network mwmigrate \
  -v /root/mw-hop-migration/hops/hop1-1.23/src:/var/www/html \
  mw-hop1-1.23:latest \
  bash -c "
    cat > /var/www/html/LocalSettings.php <<'EOF'
<?php
\$wgDBtype = 'mysql';
\$wgDBserver = 'mw-mariadb';
\$wgDBname = 'my_wiki';
\$wgDBuser = 'root';
\$wgDBpassword = 'migrate_temp_pw';
\$wgServer = 'http://localhost';
\$wgScriptPath = '';
EOF
    php maintenance/update.php --quick
  "
</nowiki>
</pre>

Minimal <code><nowiki>LocalSettings.php</nowiki></code> only — '''no extensions loaded during the hop chain''', deliberately: the goal at this stage is walking the core DB schema forward through every LTS version, not reconciling extension-specific schema/data, which happens once at the end on the final 1.43 codebase (Phase 5).

'''Verify after every hop''' before moving to the next: <code><nowiki>update.php</nowiki></code> exits 0 with no fatal errors; spot-check row counts are unchanged (<code><nowiki>SELECT COUNT(*) FROM page;</nowiki></code> etc. inside the mariadb container) — this session confirmed 1707 pages / 3634 revisions / 163 users identical before and after the full chain.

=== 3.5 Final hop note — 1.43.2 → 1.43.9 substitution ===

Hop 6 was first attempted against <code><nowiki>mediawiki-1.43.2.tar.gz</nowiki></code>; its pinned <code><nowiki>composer.lock</nowiki></code> hit a security-advisory-driven dependency block during <code><nowiki>composer install</nowiki></code>. Fix: re-extracted <code><nowiki>mediawiki-1.43.9.tar.gz</nowiki></code> in its place (rebuilt <code><nowiki>hop6-1.43</nowiki></code>'s <code><nowiki>src/</nowiki></code> from the newer tarball) — same PHP tag (<code><nowiki>8.1-apache</nowiki></code>), same Dockerfile, same <code><nowiki>update.php --quick</nowiki></code> invocation. No other hop was affected.

----