Setup:Installation Guide/Upgrade: Difference between revisions

(Created page with " ==System requirements== '''(Virtual) Hardware requirements:''' *'''Cores:''' **'''Linux: 8 Cores''' (min. 4 Cores) **Windows: 16 Cores (min. 8 Cores) *'''RAM:''' **'''16 GB''...")
Tag: 2017 source edit
 
No edit summary
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Upgrade from BlueSpice 3 to 4}}


==System requirements==
==System requirements==
'''(Virtual) Hardware requirements:'''
===Browser===
*'''Cores:'''
{{#dpl:title=Setup:System requirements|include=#Browser}}
**'''Linux: 8 Cores''' (min. 4 Cores)
===Server environment===
**Windows: 16 Cores (min. 8 Cores)
{{#dpl:title=Setup:System requirements|include=#Server Environment}}
*'''RAM:'''
**'''16 GB''' (min.  8GB)
*
'''Operating system:'''
*We strongly recommend Linux:
**Debian 11
**Ubuntu 22.04
**CentOS 7
**more following
*You might use Windows Server 2016, but we have seen performance issues on Windows Server.
'''PHP:'''
*Php 7.4: BlueSpice 4.2.x runs completly stable
*Php 8.0: Starting with BlueSpice 4.2.4
*Php 8.1: Starting from BlueSpice 4.3.x (in planning)
{{Messagebox|boxtype=note|icon=|Note text=You might need to add external repos to get the correct php on your server! Please check your package manager for the available php versions on your system.|bgcolor=}}
{{Messagebox|boxtype=note|icon=|Note text=You might need to add external repos to get the correct php on your server! Please check your package manager for the available php versions on your system.|bgcolor=}}
==Back up the old wiki==
==Back up the old wiki==
Line 35: Line 22:
==Upgrade step 1==
==Upgrade step 1==
This step has to be completed before the ''Upgrade step 2'' further below.{{Messagebox|boxtype=warning|icon=|Note text=BlueSpice 4.x cannot process wiki pages and files that were uploaded and edited by '''deleted users'''. To prevent data loss, don't skip any upgrade steps!|bgcolor=}}
This step has to be completed before the ''Upgrade step 2'' further below.{{Messagebox|boxtype=warning|icon=|Note text=BlueSpice 4.x cannot process wiki pages and files that were uploaded and edited by '''deleted users'''. To prevent data loss, don't skip any upgrade steps!|bgcolor=}}
==='''Create a "substitute user" for deleted users'''===
===Create a "substitute user" for deleted users===
In BlueSpice 3.x, create a user with a random password:
In BlueSpice 3.x, create a user with a random password:
  php maintenance/createAndPromote.php --force DeletedUser someR4ndomPass
  php maintenance/createAndPromote.php --force DeletedUser someR4ndomPass
Line 43: Line 30:
==Sql dump==
==Sql dump==
Create the backup of your data:<syntaxhighlight lang="bash">
Create the backup of your data:<syntaxhighlight lang="bash">
mysql -u root -p bluespice > migrationdump.sql
mysqldump -u root -p bluespice > migrationdump.sql
</syntaxhighlight>
</syntaxhighlight>
==Optional files for migration==
==Optional files for migration==

Latest revision as of 10:44, 13 February 2023


System requirements

Browser

  • Microsoft Edge
  • Google Chrome
  • Firefox

Server environment

  • Operating system:
    • We strongly recommend Linux (preferably Debian 11, Ubuntu 22.04, CentOS 7)
    • You might use Windows Server starting at 2016, but we have seen performance issues on Windows Server
  • Webserver:
    • Apache 2.4.x, IIS >= 10 or nginx 1.x (nginx not possible in WikiFarm)
  • PHP:
    • PHP 8.1 / PHP 8.2
  • Database:
    • MySQL: >= 5.6 or MariaDB >= 10.3
    • MongoDB >= 4.4 (for extension CollabPads)
  • (Virtual) hardware requirements:
    • CPU:
      • Linux: 8 Cores (min. 4 Cores)
      • Windows: 16 Cores (min. 8 Cores)
    • Main memory:
      • Linux: 16 GB (min. 8GB)
      • Windows: min. 16 GB
    • Available hard drive space:
      • > 20 GB (depends on the planned storage of data)
  • Other:
    • Apache Tomcat >= 9 oder Jetty >= 9 (for PDF export and LaTexRenderer)
    • OpenSearch 2 with plugin “ingest-attachment”
    • OpenJDK >= 10
    • NodeJS 16
Note:You might need to add external repos to get the correct php on your server! Please check your package manager for the available php versions on your system.

Back up the old wiki

In BlueSpice 3, create a temporary migration folder and copy all necessary data:

mkdir /tmp/migration
cd /tmp/migration
wikifolder=/path/to/wikifolder
cp -r $wikifolder/images .
cp -r $wikifolder/extensions/BlueSpiceFoundation/config .
cp -r $wikifolder/LocalSettings.* .
#check for for locals in settings.d
find $wikifolder/settings.d/ -iname '*.local.php' -exec cp --parent {} /tmp/migration \;

Also search for specialized php files in settings.d (normally 090- or 099- ).

Upgrade step 1

This step has to be completed before the Upgrade step 2 further below.

Warning!BlueSpice 4.x cannot process wiki pages and files that were uploaded and edited by deleted users. To prevent data loss, don't skip any upgrade steps!

Create a "substitute user" for deleted users

In BlueSpice 3.x, create a user with a random password:

php maintenance/createAndPromote.php --force DeletedUser someR4ndomPass
Note:You may need to temporarily disable authentication plugins like LDAP-Stack, SAML or OpenIDConnect extensions.

Get the user_id of the substitute user by running the following command in the database:

SELECT user_id FROM user WHERE user_name = "DeletedUser";

Sql dump

Create the backup of your data:

mysqldump -u root -p bluespice > migrationdump.sql

Optional files for migration

If any of the following features apply to your installation, check if migration steps are necessary. In that case, add everything to your tar file and send it to the new server.

Examples of files that you might have to consider:

  • ssl-certs
  • apache.conf
  • ldapprovider.json
  • kerberos files (krb5.conf/keyfile)

Migrate to the new wiki

Grep LocalSettings.php for wgDB

grep wgDB LocalSettings.*
LocalSettings.local.php:$wgDBserver = "Your-IP";
LocalSettings.local.php:$wgDBname = "Your-datbase-name";
LocalSettings.local.php:$wgDBuser = "Your-database-user";
LocalSettings.local.php:$wgDBpassword = "Your-password";

and create the database and DBuser with the DBpassword. Grant all on database to the DBuser in mysql. Migrate the data:

mysql -u root -p bluespice < migration.sql 
cp -r images $wikifolder
cp -r extensions $wikifolder
cp -r LocalSettings.php $wikifolder
setWikiPerm $wikifolder

Modify LocalSettings.php

Replace:

$wgLogo = "$wgResourceBasePath/resources/assets/wiki.png";

with:

$wgLogos = [ '1x' => "$wgResourceBasePath/resources/assets/wiki.png" ];
  • Check other LocalSettings.* for individual configurations from the old BlueSpice installation.
  • Compare the migrated settings.d/*.local.php with the new settings.d/*.php and check for individual (probably deprecated) configurations. Do the same with 09*-xx.php.
  • Copy to $wikifolder/settings.d/ what is needed.

Upgrade step 2

Assign all pages and files without a valid editor user to your newly created substitute user:

cd $wikifolder
 php extensions/BlueSpiceFoundation/maintenance/PrepareActorMigration.php --unknownUserId=<user-id-from-step I. > --unknownUserName=DeletedUser

Optional

  • Copy the following files (if applicable in your case):apache.conf, krb5.conf, Kerberos-key, ldapprovider.json
  • Add to VirtualHost in Apache.conf after rewrite rules:
AllowEncodedSlashes NoDecode

Last steps

Run the following maintenance scripts:

cd $wikifolder
php maintenance/update.php --quick
php extensions/BlueSpiceExtendedSearch/maintenance/initBackends.php --quick
php extensions/BlueSpiceExtendedSearch/maintenance/rebuildIndex.php --quick

screen 
    while  [ "$(php maintenance/showJobs.php)" != "0" ]; do php maintenance/runJobs.php --maxjobs 100; done

The last step will take a while.

Known possible issues after the update

Problems with VisualEditor

Add in includes/libs/http/MultiHttpClient.php after line 327:

curl_setopt( $ch, CURLOPT_SSL_VERIFYHOST, 0 );
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, 0 );



To submit feedback about this documentation, visit our community forum.