TheaterEncyclopedie:Upgrading MediaWiki 1.23.11
Inleiding
Eind 2017 is begonnen aan het Project technische verbetering TheaterEncyclopedie. Onderdeel van dit project is een upgrade van de MediaWiki-software (en gebruikte extensies en skin). Daarnaast is er een beperkt aantal uitbreidingen en aanpassingen ten behoeve van de nieuwe vormgeving.
Tot voorjaar 2018 maakt de TheaterEncyclopedie gebruik van MediaWiki versie 1.23.11 - TheaterEncyclopedie 1.0.
Deze pagina geeft een overzicht van de procedure en keuzes/beslissingen voor de upgrade van de MedaWiki software. Afhankelijke daarvan (volgend daarop) is de implementatie van de nieuwe vormgeving.
Voor de upgrade procedure is tevens gebruik gemaakt van de ervaringen die is opgedaan bij het inrichten van de Testomgeving.
Zie ook de overlegpagina voor de problemen en oplossingen bij de upgrade.
Het resultaat van deze upgrade is de TheaterEncyclopedie 2.0; de volgende upgrade van de TE naar versie 3.0 staat gepland in 2019.
Doelstelling
Inrichten van beheersbare en up-to-date productie-omgeving voor de TheaterEncyclopedie, om vervolgens de nieuwe vormgeving te kunnen implementeren.
Planning Implementatie maandag 9 juli 2018
De datum van maandag 9 juli voor de implementatie is definitief! Voor deze implementatie moeten een paar stappen gezet worden die we goed met elkaar moeten afspreken en plannen. Hieronder een voorstel voor de procedure:
Datum | Stap | Wat | Wie | Opmerkingen |
---|---|---|---|---|
25 juni 2018 | 1 | Aankondigen update nieuwe website en dat website op ??? Uit de lucht gaat voor wijzigingen. Nog wel te raadplegen, niet meer editen. | Tuja/Gonneke | De tekst plaatsen op MediaWiki:Sitenotice dan verschijnt deze op iedere wikipagina (Gonneke en Tuja zijn op vakantie en op 2 juli weer aanwezig). IdP (overleg) 13 jun 2018 11:42 (CEST) Bart en ik zorgen ervoor dat deze melding op 25 juni geplaatst wordt. |
5 juli 2018 | 2 | Deadline voor de laatste wijzigingen voor migratie! | Bart/Ilonka | |
9 juli 2018 | 3 | Het “bevriezen” van de theaterencyclopedie.nl vanaf dat moment - dit is merkbaar voor gebruikers (ten minste de editors)! | Joris/Jasper | |
9 juli 2018 | 4 | De update van de database van test.theaterencyclopedie.nl met de laatste gegevens uit de DB van de operationele theaterencyclopedie.nl | Joris/Jasper | |
10 juli 2018 | 5 | Na seintje van Jasper en Joris dat de database is overgezet, wordt dit door Ilonka en Bart getest | Bart/Ilonka | |
6 | Het overzetten van de vormgeving en gewijzigde pagina’s op test.theaterencyclopedie (dit is met name voor Ilonka en Bart van belang) incl. finale testen | Bart/Ilonka | ||
7 | Het overzetten van test.theaterencyclopedie.nl naar “operationeel/productie” | Joris/Jasper | ||
8 | Testen van de operationele omgeving (evt. correcties uitvoeren of zelfs | Allemaal | ||
9 | in nood een “fall-back”; terugzetten v.d. oude omgeving) | Joris/Jasper |
Keuzes vooraf
Voorafgaande aan de upgrade van MediaWiki zijn er nog keuzes te maken wat betreft de volgende onderwerpen: - Doelversie MediaWiki - Procedure - Planning
- Doelversie MediaWiki
- Op de Test-TE is gebruik gemaakt van MediaWiki versie 1.27.3; op dat moment de meest recente LTS versie van MediaWiki. Inmiddels is er een release 1.27.4 uitgebracht en zal volgens planning de nieuwe LTS versie 1.31.0 in juni 2018 worden uitgebracht (NB: nieuwe versies van MediaWiki verschijnen historisch gezien meestal pas in september / oktober van een jaar).
- Procedure
- Het gevolgde stappenplan upgrade voor de testomgeving is uitgangspunt voor de upgrade-procedure. Afhankelijk van de keuze van de doelversie (en andere overwegingen) kan de upgrade-procedure anders aangepakt worden. Daarbij moet sowieso rekening gehouden worden met (aansluiting op) de implementatie van de nieuwe vormgeving en een testperiode voor gebruikers van de TE.
- Planning
- De planning is afhankelijk van doelstellingen, procedure en beschikbare middelen als menskracht in de eigen organisatie en bij testers.
Upgrade procedure
De upgrade procedure is gebaseerd op de uitgevoerde upgrade t.b.v. de inrichting van de Test-TE (op VPS Wikiwerkers.nl). In grote lijnen was deze procedure als volgt:
- Voorbereiding VPS en locale installatie (XAMPP) - url, installatie directory, composer installeren, database, beveiliging
- Kopiëren/archiveren gegevens - Uitvoeren 'pending jobs", kopiëren database, afbeeldingen, configuratie
- Schone installatie MediaWiki (1.23.11) - importeren & koppelen database en testen in XAMPP (1.23 is optioneel)
- Schone installatie MediaWiki (1.27.3) - upgrade TE-database in locale omgeving (XAMPP)
- Upgrade SMW - installatie & configuratie SMW extensie in locale omgeving (XAMPP), uitvoeren update database en rebuild Semantic data
- Overbrengen naar VPS - Installatie & configuratie MW en SMW, importeren database, kopiëren afbeeldingen
- Extensies & skin - installeren en configureren van de benodigde extensies en skin
- Installatie VisualEditor - Installeren Parsoid (incl. Nodejs) en extensie, configuratie & testen.
- Overbrengen Vormgeving vanuit testomgeving - zie Implementeren Vormgeving
NB: Deze procedure is enigszins aangepast voor de upgrade van de productie-versie van de TE.
Zie ook: Gebruikerstest
Voorbereiding VPS en locale installatie op VM (XAMPP)
Deze installatie procedure gaat uit van het gebruik van een VM (zoals XAMPP). De reden hiervoor is de omvang van de database en de daarmee samenhangende 'load' van de upgrade/update procedures. Het gebruik van een VM is niet noodzakelijk en de installatie/upgrade kan eventueel rechtstreeks op het VPS uitgevoerd worden.
Actie | Beschrijving | Docs |
---|---|---|
Controle systeem VPS/VM | Controleer PHP, MySQL versies, en aanwezigheid van Composer en Nodejs libraries | Requirements |
Composer / Nodejs | Installeer zonodig Composer en Nodejs op de VM en de VPS | Composer, Composer, Nodejs download, Nodejs installeren |
url | configureer (sub-)domein VPS / url voor ontwikkelomgeving, bijv.: test.theaterencyclopedie.nl | - |
beveiliging | beperk toegang tot ontwikkelomgeving | - |
DB aanmaken | maak (lege) DB’s aan op VPS en VM (check: useraccount) |
Overige documentatie achtergronden Composer voor (Semantic) MediaWiki:
Kopiëren/archiveren gegevens
Het kopiëren van database-gegevens t.b.v. nieuwe operationele website. Tijdens het upgraden moet de 'oude' operationele website 'bevroren' worden; wijzigingen die hierop tijdens de upgrade plaatsvinden, worden niet meegenomen naar de geüpgraded website van theaterencyclopedie.nl !
Actie | Beschrijving | Docs |
---|---|---|
Run Jobs | Uitvoeren ‘pending jobs’ | Clear pending jobs documentatie |
Freeze | Stop editmogelijkheid op operationele TE | Documentatie |
Dump DB | Dumpfile (backup.sql.gz) van de operationele database maken | |
Copy DB | Kopieer dump DB naar VM & importeer in MySQL / MariaDB | - |
Schone installatie MediaWiki (1.27.3-4)
Om bij de upgradeprocedure niet gehinderd te zijn door bestaande (mogelijk verouderde) extensie en configuratie-instellingen, wordt een zogeheten "schone" (basis) installatie van MediaWiki gemaakt. Deze installatie wordt naderhand opgebouwd tot volledig functionerende installatie van de TheaterEncyclopedie op de nieuwe versie van MediaWiki.
Actie | Beschrijving | Docs |
---|---|---|
Download 1.27.3-4 | Download & uitpakken van zip | Download |
Installatie | Run web script, koppel & upgrade database. Installeer alleen de volgende extensies: Cite, Inputbox, ParserFunctions en WikiEditor | Installing |
Backup DB | Maak een back-up van geüpgraded DB | - |
Test | Visuele test van alleen het 'laden' van enkele pagina’s (NB: er zullen veel onderdelen niet correct worden weergegeven door het ontbreken van extensies!) | - |
Afbeeldingen | Optioneel: Overbrengen afbeeldingen (niet essentieel voor upgrading). NB: houdt rekening met non standaard lokatie van afbeeldingen directory. | |
Extensies | (Grotendeels) overslaan tijdens installatieprocedure; | Installeer alleen essentiele extensies |
Essentiële extensies | Zeer beperkt aantal extensies is essentieel: Regex, ParserFunctions | - |
Upgrade SMW
De upgrade van Semantic MediaWiki van de huidige 2.2.2 versie naar 2.5 wordt uitgevoerd op de VM m.b.v. Composer. Na de update van de semantische gegevens wordt de geüpgraded database overgebracht naar VPS. Voorafgaande aan het overzetten van de database wordt ook de nieuwe versie van Semantic MediaWiki op de VPS geïnstalleerd.
NB-1: De Composer-commando's gaan uit van een lokale installatie van Composer; zo nodig aanpassen bij een systeem-brede installatie!
NB-2: Semantic MediaWiki maakt gebruik van diverse Semantische Extensies, waaronder SemanticForms. SemanticForms heet tegenwoordig PageForms. De overige extensie moeten zonodig up-to-date gebracht worden.
Actie | Beschrijving | Docs |
---|---|---|
Installeer SMW | Installeer SMW 2.2.2. op VM m.b.v. Composer (wellicht mogelijk om over te slaan en direct naar upgrade?) | Composer |
Test | Visuele test enkele pagina’s | - |
Update SMW | php composer.phar require mediawiki/semantic-media-wiki:~2.5 --update-with-dependencies | |
Test | Mogelijk is het nodig om enkele SMW-extensie uitzetten (SemanticForms bijv. geeft problemen op XAMMP) | |
Update DB | Voor het (PHP) update-script uit om de Database-tables bij te werken; zie opdracht update.php hieronder. | |
Rebuild data | Werk de semantische gegevens in de database bij | rebuildData |
SemanticResultFormats | Installeer de extensie SemanticResultFormats m.b.v. composer (zie hieronder: standaard installatie) | |
Update extensies | Installeer en update zonodig de overige "Semantische uitbreidingen" | Speciaal:Softwareversie |
Configuraties LocalSettings.php | Zie voorbeeld hieronder. | |
Test | Visuele test enkele pagina's | - |
Backup DB | Maak een back-up van de Database | - |
VPS DB plaatsen | Backup DB-file overzetten naar VPS en importeren in MySQL | |
Config VPS | Configuratie extensies / LocalSettings.php (zonodig) overnemen van VM | |
Test VPS | Visuele test van enkele pagina's |
Composer commando installatie SMW 2.2.2 :
php composer.phar require mediawiki/semantic-media-wiki “2.2.2" --update-no-dev
Composer commando installatie SMW 2.5 :
php composer.phar require mediawiki/semantic-media-wiki:~2.5 --update-with-dependencies
Comando voor update van Semantische tabellen in DB:
php maintenance/update.php --skip-external-dependencies
NB: Dit script kan geruime tijd (10 minuten) in beslag nemen! ("updating page_id from…. to 600981").
Commando voor de update van Semantische informatie in de DB:
php extensions/SemanticMediaWiki/maintenance/rebuildData.php -d 50 -v
De d geeft vertraging van 50 ms…. kan weggelaten worden bij de update op de VM:
php extensions/SemanticMediaWiki/maintenance/rebuildData.php -v
Herstarten vanaf bepaald punt nadat bijwerken is gestopt, bijvoorbeeld:
php extensions/SemanticMediaWiki/maintenance/rebuildData.php -v -s 257381
Composer commando voor installatie SemanticResultFormats:
php composer.phar require mediawiki/semantic-result-formats ‘2.*’
Configuratie LocalSettings.php (NB: zonder de configs van de geïnstalleerde extensies!!):
enableSemantics(' <SUBDOMEIN BV TEST>.theaterencyclopedie.nl');
Overbrengen naar VPS - Schone installatie
Actie | Beschrijving | Docs |
---|---|---|
Importeer DB | Importeer de Backup DB van het VM | |
Installeer MW | Installeer (of kopieer & pas LocalSettings.php aan) bestanden vanaf VM | - |
Afbeeldingen | Kopieer de images directory (vanaf operationele site), (NB: zonodig chown www-data). NB: houdt rekening met non standaard lokatie van images directory. | - |
Test | Visuele test van afbeeldingen op enkele pagina's | -- |
Upgrade extensies | 1-voor-1 up-to-date versie installeren en testen; NB: niet alle extensies waren in gebruik! | Overzicht Extensies |
Configuratie in LocalSettings.php t.b.v. toegangsbeveiliging (deels gegenereerd door installatiescript!):
# The following permissions were set based on your choice in the installer $wgGroupPermissions['*']['createaccount'] = false; $wgGroupPermissions['*']['edit'] = false; # Read access only for logged in users # $wgGroupPermissions['*']['read'] = false; # Uitschakelen omdat VE niet met private wiki's werkt!
en:
# BM: StringFunctions $wgPFEnableStringFunctions = true; # BM: Gallery Options $wgGalleryOptions = array ( 'imagesPerRow' => 5, // Default number of images per-row in the gallery 'imageWidth' => 200, // Width of the cells containing images in galleries (in "px") 'imageHeight' => 200, // Height of the cells containing images in galleries (in "px") 'captionLength' => 20, // Length of caption to truncate (in characters) 'showBytes' => true, // Show the filesize in bytes in categories BM: aangepast van files naar true vanwege foutmelding 'mode' => 'packed-hover', // One of "traditional", "nolines", "packed", "packed-hover", "packed-overlay" );
Uitbreidingen voor Nieuwe vormgeving
Ten behoeve van de implementatie van de Nieuwe Vormgeving is een beperkt aantal aanpassingen en/of uitbreidingen van het MediaWiki en OS benodigd:
- Skin
- Installatie van de skin "Tweeki"
- Font
- Plaatsen van standaar UvA Font-files (bij voorkeur binnen directory skin tweeki)
- Visual Editor
- Installatie van de extensie "VisualEditor", die afhankelijk is van het "Parsoid"-script (omzetten wikitekst in html en vice versa) en de library "Nodejs".
- Ovige extensies
- Naast de extensie VE zijn twee additionele extensies gebruikt: Shariff (delen op social media) en Widgets (t.b.v. html/js/css uitbreidingen voor de vormgeving).
De vormgeving zelf wordt verder via de gebruikersinterface van MediaWiki geïmplementeerd.
Skin
Voor de Nieuwe Vormgeving is de skin Tweeki (versie 1.0.4) als basis gekozen. Deze skin maakt gebruik van Twitter's Bootstrap (versie 3.3.7).
Actie | Beschrijving | Docs |
---|---|---|
Download | Zie instructies webpagina | Skin:Tweeki |
Installeer | Aanpassingen in LocalSettings.php volgens instructie | Skin:Tweeki |
Configuratie | Aanpassingen in LocalSettings.php | zie hieronder |
Test | Visuele test van enkele pagina's | - |
Configuratie Tweeki in LocalSettings.php:
## Default skin: you can change the default skin. Use the internal symbolic ## names, ie 'vector', 'monobook': $wgDefaultSkin = "tweeki";
## BM: Tweeki configuratie $wgTweekiSkinHideable = array( 'firstHeading', 'sidebar-right' ); $wgTweekiSkinHideAnon = array( 'subnav' => false ); // NB: subnav is default hidden voor Anon! $wgTweekiSkinHideLoggedin['subnav'] = true; $wgTweekiSkinGridRight = array( "mainoffset" => 1, "mainwidth" => 9, "rightoffset" => 0, "rightwidth" => 2 ); $wgTweekiSkinGridNone = array( "mainoffset" => 1, "mainwidth" => 10 );
Plaatsen van Font-files
Actie | Beschrijving | Docs |
---|---|---|
Aanmaken directory | ../w/skins/Tweeki/fonts-uva/ |
- |
Installeren files | Uploaden van zip-archief met (ca. 10) font-files t.b.v. MetaWeb lettertype conform huisstijl UvA. Unzip archief. | Archief beschikbaar in projectgroep |
Configuratie | Niet nodig | Via gebruikersinterface |
Extensie VisualEditor
Actie | Beschrijving | Docs |
---|---|---|
Nodejs | Check - reeds geïnstalleerd aan begin procedure | |
Installeer Parsoid | Installeer Parsoid conform documentatie. Parsoid kan in principe overall geïnstalleerd worden. De “standaard” locatie voor installatie van parsoid is /opt/parsoid | Start hier. En vervolgens: Setup (kan ook 'normale' setup kiezen), en zie ook: Setup. |
Autostart Parsoid | Automatisch starten van Parsoid bij opstarten VPS. NB: Verschilt per OS; zie documentatie. | Setup |
Installeer VE | Extensie VisualEditor installeren conform standaard documentatie | Extensie VE |
Extensie VE-for-Pageform | Extensie om VE met PageForm te laten samenwerken installeren conform documentatie | GIT |
Test | Het is zaak deze extensie uitgebreid te testen voor gebruik: editing, saving, switching, cancelling, etc. |
Configuratie Parsoid in config.yaml :
# Configure Parsoid to point to your MediaWiki instances. mwApis: - # This is the only required parameter, # the URL of you MediaWiki API endpoint. uri: 'http:// <SUBDOMEIN BV TEST>.theaterencyclopedie.nl/w/api.php' # The "domain" is used for communication with Visual Editor # and RESTBase. It defaults to the hostname portion of # the `uri` property above, but you can manually set it # to an arbitrary string. It must match the "domain" set # in $wgVirtualRestConfig. domain: 'localhost2' # optional
Configuratie VisualEditor in LocalSettings.php (voorbeeld):
## BM: VisualEditor configuratie wfLoadExtension( 'VisualEditor' ); # Enable by default for everybody $wgDefaultUserOptions['visualeditor-enable'] = 0; # Optional: Set VisualEditor as the default for anonymous users # otherwise they will have to switch to VE # $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor"; # Don't allow users to disable it # $wgHiddenPrefs[] = 'visualeditor-enable'; # OPTIONAL: Enable VisualEditor's experimental code features #$wgDefaultUserOptions['visualeditor-enable-experimental'] = 1; # Enable skins for VisualEditor $wgVisualEditorSupportedSkins[] = 'tweeki'; $wgVirtualRestConfig['modules']['parsoid'] = array( // URL to the Parsoid instance // Use port 8142 if you use the Debian package 'url' => 'http:// <SUBDOMEIN BV test> .theaterencyclopedie.nl:8000', // Parsoid "domain", see below (optional) 'domain' => 'localhost2', // Parsoid "prefix", see below (optional) 'prefix' => 'localhost2' );
Installeer de overige nieuwe Extensies
Actie | Beschrijving | Docs |
---|---|---|
Extensie Shariff | Installeer de extensie conform documentatie | MediaWiki, Github |
Instellingen aanpassen | Taal & Service (Facebook & Twitter) instellen | Zie code hieronder voor Shariff.php |
Testen Sharif | Visuele test op Hoofdpagina; share-buttons zichtbaar & werkend? | - |
Extensie Widgets | Installeer de extensie conform documentatie - standaard installatie. Let op rechten template-folder | MediaWiki |
Testen Widgets | Visuele test op Hoofdpagina; geen {{#widget| ... }}-codes meer op pagina? | - |
Aanpassing in Shariff.php code (r.60-61):
//Get page title and URL $output = '<div class="shariff noprint" data-lang="nl" data-backend-url="'.$wgScriptPath.'/extensions/Shariff/shariff-backend/" data-services="["twitter","facebook"]"></div>';
Verhuizing naar hoofd-domein
Na de gebruikerstesten is het nog nodig om de website te verhuizen van het gebruikte sub-domein (bv. test.theaterencyclopedie.nl) naar het hoofd-domein (www.theaterencyclopedie.nl).
NB1: Toegangsrechten (editing) aanpassen naar wens gebruikers.
NB2: Behalve de (evt.) aanpassingen in de DNS zijn hiervoor ook enkele aanpassingen in de LocalSettings.php benodigd. In ieder geval:
- $wgScriptPath (MediaWiki)
- $wgServer (MediaWiki)
- enableSemantics(); (Semantic MediaWiki)
- $wgVirtualRestConfig (VE)
Overige aandachtspunten
Er is een aantal punten dat niet in bovenstaande procedure is opgenomen, maar wellicht wel in aanmerking komt voor aanpassing/implementatie:
- Testen PHP-scripts voor update van de TE met gegevens uit Adlib
- Implementeren van SSL (https://) voor versleuteling van gebruikersnamen en wachtwoorden bij inloggen
- Niet-standaard lokatie van afbeeldingen (directory /images )
- Consequent gebruik van www.theaterencyclopedie.nl of theaterencyclopedie.nl (zonder www.)