Difference between revisions of "XiphInfra:Wiki VM"

From XiphWiki
Jump to navigation Jump to search
 
(8 intermediate revisions by 3 users not shown)
Line 7: Line 7:
 
|url=https://wiki.xiph.org}}
 
|url=https://wiki.xiph.org}}
  
As the name suggest, the Wiki VM runs this [http://mediawiki.org MediaWiki] instance.
+
As the name suggests, the Wiki VM runs this [http://mediawiki.org MediaWiki] instance.
  
It runs an Apache2 server with PHP module, in front of it is a reverse proxy (nginx) running on Catfish. If you need to add
+
It runs an Apache2 server with a PHP module. In front of it is a reverse proxy (nginx) running on Catfish.
or adjust things like headers and the HTTPS redirect, check the nginx config on Catfish, not the Apache2 config.
+
If you need to add or adjust things like headers and the HTTPS redirect, check the nginx config on Catfish, not the Apache2 config.
  
 
The current version of MediaWiki and the installed Modules can be found [[Special:Version|here]].
 
The current version of MediaWiki and the installed Modules can be found [[Special:Version|here]].
  
 +
== Add Wiki Account ==
 +
<div style="background-color: #B4CFEC; padding: 5px; border: 1px #888 solid;">Currently, account creation on the Wiki is disabled due to massive amounts of spam. Therefore, until we find a solution for this, Users are asked to go to the #xiph IRC channel and ask for an account there, which a wiki sysop has to create.</div>
 +
 +
Below is an excerpt from the MediaWiki Page, describing how to create an Account:
 +
 +
# Go to {{Special:UserLogin}}, when logged in as a [[Special:ListUsers/sysop|sysop]].
 +
# Click on "Create an account" link to get to the account creation form.
 +
# Enter a username and an email address, and click the "by email" button. Note you need <code>$wgEnableEmail=true</code> or else the sysop must pick a password and send it to the user.
 +
# The account will be created with a random password which is then emailed to the given address (as with the "forgot password" feature). The user will be requested to change password at first login; when he does this, his e-mail address will also be marked as confirmed.
 +
#:<small>When you click the "create account" button instead, you have to manually send the user his password. If you've set <code>$wgMinimalPasswordLength</code> and you've left the password field blank, the user will be emailed an e-mail address confirmation request but will be unable to access {{Special:Confirmemail}} to perform the confirmation. Instead, the user will get an error (unless you've added it to <code>$wgWhitelistRead</code>); the user will be able to login with a blank password and then confirm email, but their password will not have been reset (it will have to be reset manually).</small>
  
 
== Important Modules ==
 
== Important Modules ==
 
These are the most important modules that we have in use:
 
These are the most important modules that we have in use:
  
=== Math ===
+
=== Math and Mathoid ===
The [https://www.mediawiki.org/wiki/Extension:Math Math] module allows us to use equations similar as in LaTeX:
+
The [https://www.mediawiki.org/wiki/Extension:Math Math] module allows us to use equations similar to LaTeX:
  
 
<code><nowiki><math>E=mc^2</math></nowiki></code> will display as <math>E=mc^2</math>
 
<code><nowiki><math>E=mc^2</math></nowiki></code> will display as <math>E=mc^2</math>
Line 40: Line 50:
 
More information about the config can be found on the [https://www.mediawiki.org/wiki/Extension:Math/advancedSettings Math/advancedSettings] page.
 
More information about the config can be found on the [https://www.mediawiki.org/wiki/Extension:Math/advancedSettings Math/advancedSettings] page.
  
Once the Math extension is configure, as mentioned, it needs Mathoid to render MathML and SVGs. It's a bit tricky to install
+
Once the Math extension is configured, it needs Mathoid to render MathML and SVGs.
therefore below is a short guide how to do so:
+
It's a bit tricky to install so have a look at the short guide below:
  
 
==== Fetch the source code ====
 
==== Fetch the source code ====
Line 61: Line 71:
  
 
==== Install dependencies ====
 
==== Install dependencies ====
Inside the mathoid folder do:
+
Inside the mathoid folder, run:
  
 
  npm install
 
  npm install
  
 
==== Change config ====
 
==== Change config ====
Remove the default config symlink and crate one for the prod config:
+
Remove the default config symlink and create one for the prod config:
  
 
  rm config.yaml
 
  rm config.yaml
 
  ln -s config.prod.yaml config.yaml
 
  ln -s config.prod.yaml config.yaml
  
Adjust the config accordingly, currently the config looks similar to:
+
Adjust the config accordingly. Currently the config looks like this:
  
 
<syntaxhighlight lang="yaml">
 
<syntaxhighlight lang="yaml">
Line 116: Line 126:
 
  npm start
 
  npm start
  
If it start successfully, go to a Wiki Page, edit it and add a simple equation and preview the page.
+
If it starts successfully, go to a Wiki Page, edit it, add a simple equation and preview the page.
(Make sure to use a unique equation, as caching could prevent that Mathoid is used, if the equation already exists.)
+
(Make sure to use a unique equation, as caching could prevent Mathoid from being used.)
  
 
If everything works as expected, write a systemd unit or such and start Mathoid with it, for production use.
 
If everything works as expected, write a systemd unit or such and start Mathoid with it, for production use.
 +
 +
==== Troubleshooting ====
  
 
Maybe useful for debugging, you can use curl to make a request to Mathoid like this:
 
Maybe useful for debugging, you can use curl to make a request to Mathoid like this:
  
  curl -d 'q=E=fobarmc^2' http://127.0.0.1:10042/
+
curl -d 'q=E=fobarmc^2' http://127.0.0.1:10042/
 +
 
 +
If you get errors like <code>spawn java ENOENT</code> make sure you have set
 +
img: false
 +
in your config, otherwise it will try to use [http://xmlgraphics.apache.org/batik/download.html Apache™ Batik], which requires Java.
 +
I guess not having PNGs is a fair tradeoff, if that saves us from having to use Java on the VM.
 +
 
 +
If there are problems while installing dependencies, make sure your nodejs version is recent enough.
 +
You can try removing its modules and reinstalling them:
 +
 
 +
rm -rf ./node_modules
 +
npm cache clear
 +
npm install
 +
 
 +
=== SyntaxHighlight (GeSHi) ===
 +
This is used to highlight code blocks:
 +
 
 +
<nowiki><syntaxhighlight lang="php">
 +
$foo = "bar";
 +
</syntaxhighlight></nowiki>
 +
 
 +
will display as:
 +
 
 +
<syntaxhighlight lang="php">
 +
$foo = "bar";
 +
</syntaxhighlight>
 +
 
 +
Luckily, this one is much easier to install.
 +
It does not (contrary to what the name suggests) depend on GeSHi anymore,
 +
but has switched to [http://pygments.org Pygments], so make sure that is installed.
 +
 
 +
That's it! (Phew, much easier compared to Mathoid...)

Latest revision as of 16:46, 26 February 2021

Wiki VM
Maintainer(s) ePirat
Host mf4
IPs 192.168.2.180
Service(s) Wiki

https://wiki.xiph.org


As the name suggests, the Wiki VM runs this MediaWiki instance.

It runs an Apache2 server with a PHP module. In front of it is a reverse proxy (nginx) running on Catfish. If you need to add or adjust things like headers and the HTTPS redirect, check the nginx config on Catfish, not the Apache2 config.

The current version of MediaWiki and the installed Modules can be found here.

Add Wiki Account

Currently, account creation on the Wiki is disabled due to massive amounts of spam. Therefore, until we find a solution for this, Users are asked to go to the #xiph IRC channel and ask for an account there, which a wiki sysop has to create.

Below is an excerpt from the MediaWiki Page, describing how to create an Account:

  1. Go to Special:UserLogin, when logged in as a sysop.
  2. Click on "Create an account" link to get to the account creation form.
  3. Enter a username and an email address, and click the "by email" button. Note you need $wgEnableEmail=true or else the sysop must pick a password and send it to the user.
  4. The account will be created with a random password which is then emailed to the given address (as with the "forgot password" feature). The user will be requested to change password at first login; when he does this, his e-mail address will also be marked as confirmed.
    When you click the "create account" button instead, you have to manually send the user his password. If you've set $wgMinimalPasswordLength and you've left the password field blank, the user will be emailed an e-mail address confirmation request but will be unable to access Special:Confirmemail to perform the confirmation. Instead, the user will get an error (unless you've added it to $wgWhitelistRead); the user will be able to login with a blank password and then confirm email, but their password will not have been reset (it will have to be reset manually).

Important Modules

These are the most important modules that we have in use:

Math and Mathoid

The Math module allows us to use equations similar to LaTeX:

<math>E=mc^2</math> will display as

The extension uses Mathoid to render equations, this is how it's configured:

/* Math */
$wgUseTeX           = true;
$wgTexvc            = "$IP/extensions/Math/math/texvc";
$wgMathPath         = "{$wgUploadPath}/math";
$wgMathDirectory    = "{$wgUploadDirectory}/math";
$wgMathMathMLUrl    = "http://127.0.0.1:10042";
$wgMathValidModes   = array(MW_MATH_MATHML, MW_MATH_PNG, MW_MATH_SOURCE);

/* Set Mathoid as default rendering option */
$wgDefaultUserOptions['math'] = MW_MATH_MATHML;

More information about the config can be found on the Math/advancedSettings page.

Once the Math extension is configured, it needs Mathoid to render MathML and SVGs. It's a bit tricky to install so have a look at the short guide below:

Fetch the source code

cd /opt/
git clone https://github.com/wikimedia/mathoid

Install a relatively new node.js version

The packaged version is probably too old, so you should download one from the Node.js download page. For example:

wget https://nodejs.org/dist/v4.2.4/node-v4.2.4-linux-x64.tar.xz
tar xfv ./node-v4.2.4-linux-x64.tar.xz
mv ./node-v4.2.4-linux-x64.tar.xz /opt/node-v4.2.4

Add node binaries to your PATH

echo export PATH=/opt/node-v4.2.4/bin:$PATH >> ~/.bashrc

Install dependencies

Inside the mathoid folder, run:

npm install

Change config

Remove the default config symlink and create one for the prod config:

rm config.yaml
ln -s config.prod.yaml config.yaml

Adjust the config accordingly. Currently the config looks like this:

# Number of worker processes to spawn.
# Set to 0 to run everything in a single process without clustering.
# Use 'ncpu' to run as many workers as there are CPU units
num_workers: ncpu

# Log error messages and gracefully restart a worker if v8 reports that it
# uses more heap (note: not RSS) than this many mb.
worker_heap_limit_mb: 500

# Logger info
logging:
  level: warn
  streams:
  # Use gelf-stream -> logstash
  #- type: gelf
  #  host: logstash1003.eqiad.wmnet
  #  port: 12201

# Statsd metrics reporter
metrics:
  #type: statsd
  #host: statsd.eqiad.wmnet
  #port: 8125

services:
  - name: mathoid
    module: ./app.js
    conf:
      interface: 127.0.0.1
      port: 10042
      svg: true
      img: false
      texvcinfo: true
      speech: true
      sppechOn: false

Try it

Let's try to start it:

npm start

If it starts successfully, go to a Wiki Page, edit it, add a simple equation and preview the page. (Make sure to use a unique equation, as caching could prevent Mathoid from being used.)

If everything works as expected, write a systemd unit or such and start Mathoid with it, for production use.

Troubleshooting

Maybe useful for debugging, you can use curl to make a request to Mathoid like this:

curl -d 'q=E=fobarmc^2' http://127.0.0.1:10042/

If you get errors like spawn java ENOENT make sure you have set

img: false

in your config, otherwise it will try to use Apache™ Batik, which requires Java. I guess not having PNGs is a fair tradeoff, if that saves us from having to use Java on the VM.

If there are problems while installing dependencies, make sure your nodejs version is recent enough. You can try removing its modules and reinstalling them:

rm -rf ./node_modules
npm cache clear
npm install

SyntaxHighlight (GeSHi)

This is used to highlight code blocks:

<syntaxhighlight lang="php">
$foo = "bar";
</syntaxhighlight>

will display as:

$foo = "bar";

Luckily, this one is much easier to install. It does not (contrary to what the name suggests) depend on GeSHi anymore, but has switched to Pygments, so make sure that is installed.

That's it! (Phew, much easier compared to Mathoid...)