Gebruiker:Bmulckhu/upgrade

Uit TheaterEncyclopedie
Ga naar: navigatie, zoeken

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.

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.

Doelstelling

Inrichten van beheersbare en up-to-date productie-omgeving voor de TheaterEncyclopedie, om vervolgens de nieuwe vormgeving te kunnen implementeren.

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:

  1. Voorbereiding VPS en locale installatie (XAMPP) - url, installatie directory, composer installeren, database, beveiliging
  2. Kopiëren/archiveren gegevens - Uitvoeren 'pending jobs", kopiëren database, afbeeldingen, configuratie
  3. Schone installatie MediaWiki (1.23.11) - importeren & koppelen database en testen in XAMPP (1.23 is optioneel)
  4. Schone installatie MediaWiki (1.27.3) - upgrade TE-database in locale omgeving (XAMPP)
  5. Upgrade SMW - installatie & configuratie SMW extensie in locale omgeving (XAMPP), uitvoeren update database en rebuild Semantic data
  6. Overbrengen naar VPS - Installatie & configuratie MW en SMW, importeren database, kopiëren afbeeldingen
  7. Extensies & skin - installeren en configureren van de benodigde extensies en skin
  8. Installatie VisualEditor - Installeren Parsoid (incl. Nodejs) en extensie, configuratie & testen.
  9. Overbrengen Vormgeving vanuit testomgeving - zie Implementeren Vormgeving

NB: Deze procedure is enigszins aangepast voor de upgrade van de productie-versie van de TE.

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.

Voorbereidingen
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 !

Kopiëren van de Database
Actie Beschrijving Docs
Run Jobs Uitvoeren ‘pending jobs’ Clear pending jobs
Freeze Stop editmogelijkheid op operationele TE [1]
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.

Installeren MediaWiki op VM
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 Overbrengen afbeeldingen niet essentieel voor upgrading
Extensies: overslaan
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.

Upgrade procedure Semantic MediaWiki
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
Rebuild data Werk de semantische gegevens in de database bij rebuildData
SemanticResultFormats Installeer de extensie SemanticResultFormats m.b.t. 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

Overbrengen naar VPS
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) -
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"
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).

Installeren Skin:Tweeki
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 
);

Extensie VisualEditor

VisualEditor installeren en configureren
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

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).

NB: Behalve de aanpassingen in de DNS zijn hiervoor ook enkele aanpassingen in de LocalSettings.php benodigd.

Overgenomen van "https://theaterencyclopedie.nl/w/index.php?title=Gebruiker:Bmulckhu/upgrade&oldid=2270907"