Configuring Math Plugin for codeBeamer: Mathematical Formulas in Wiki (pre 20.11-LTS Carmen)

Math plugin is capable of rendering Mathematical Formulas in Wiki. An example of this:

This plugin displays latex formulas and uses a few external programs that must be installed on codeBeamer's host for this plugin. This guide describes the installation steps for making the plugin functional.

20.11-LTS (Carmen)

There is no need to install Latex on the host, rendering is done by Javascript by MathJax 2.7.7.

Please install PhantomJS on your host machine.

Windows (before 20.11-LTS Carmen)

Windows requires manual installation and configuration of the following packages:

Installing MiKTeX (latex for windows) (before 20.11-LTS Carmen)

For downloading MiKTeX download the Basic installation package from here. Choose the appropriate 32 bit or 64 bit installer depending whether your Windows is 32 or 64 bit.

Install the package (leaving the default settings for everything, (except Installing missing packages on-the-fly, set it to yes)), and make a note of the installation directory (a typical example of installation directory is: "C:\Program Files (x86)\MiKTeX 2.9")

Installing Ghostscript (before 20.11-LTS Carmen)

Ghostscript is used for PostScript language processing by the Math plugin and can be installed from here: http://www.ghostscript.com/download/gsdnld.html. Choose and download the appropriate 32 or 64-bit "Ghostcript GPL Release" package from there, and install that.

During the installation leave all settings on default, and make a note of the installation directory (for example "C:\Program Files (x86)\gs\gs9.05").

Installing ImageMagick (before 20.11-LTS Carmen)

ImageMagick is used for converting between different image formats. Again choose and download the appropriate 32 or 64-bit package and install that http://www.imagemagick.org/script/binary-releases.php#windows.

Currently supported version: ImageMagick-6.7.6-Q16

https://ftp.icm.edu.pl/packages/ImageMagick/binaries/

During the installation leave all settings on default, and make a note of the installation directory (for instance, "C:\Program Files (x86)\ImageMagick-6.7.6-Q16\").

Configuring codeBeamer (before 20.11-LTS Carmen)

After these installations are done, you'll have to "tell" codeBeamer where these programs are. Unfortunately, putting these on the system classpath is not enough, because Windows may pick up wrong executables from the path. Instead you will need to edit the "C:\CB\tomcat\webapps\cb\config\path.txt" file (use your codeBeamer location instead of "C:\CB"). Edit that file, and add the paths of the just installed packages this way:

C:\CB-7.0\libexec;C:\Program Files (x86)\MiKTeX 2.9\miktex\bin;C:\Program Files (x86)\gs\gs9.05\bin;C:\Program Files (x86)\ImageMagick-6.7.6-Q16\

Important: add the "\bin" to the paths of MiKTeX and Ghostscript, but NOT for the ImageMagick package.

After this is done, restart the codeBeamer service so that the settings can be activated. You are now all set: the Math plugin is ready to be used.

See: Configuring search PATH where external executables are found

Linux (before 20.11-LTS Carmen)

On Linux, the installation is much simpler. Just use the standard installer tool for your distribution to install 3 packages: texlive-latex-base, imagemagick and ghostscript.

CentOS (before 20.11-LTS Carmen)

On CentOS this can be done using this commands:

sudo yum -y install ImageMagick \
		texlive-latex \
		texlive-latex-bin \
		texlive-latexconfig \
		texlive-amsmath \
		texlive-dvipng \
		texlive-dvipng-bin \
		texlive-dvips \
		texlive-dvips-bin \
		texlive-texconfig \
		texlive-texconfig-bin \
		texlive-metafont \
		texlive-metafont-bin \
		texlive-collection-fontsrecommended
sudo yum -y groupinstall "fonts"

Suse (before 20.11-LTS Carmen)

On Suse this can be done using this command:

sudo zypper install texlive-latex textlive-bin-latex

Ubuntu (before 20.11-LTS Carmen)

On Ubuntu this can be done using this command:

sudo apt-get install texlive-latex-base imagemagick ghostscript

Troubleshooting (before 20.11-LTS Carmen)

If the Math plugin does not render the formulas correctly, check the following:

• Did you restart codeBeamer after installation?
• open the $CB_HOME/tomcat/logs/cb.txt log file and look for "MathPlugin" logs. If there is any error during the execution of the external programs above, there should be some kind of hint about that. Note: you may see some warnings during latext-processing, but that is typically not a problem.
• If all 3 packages are installed properly, test their versions by executing these commands:

latex --version

MiKTeX-pdfTeX 2.9.7029 (1.40.20)
Copyright (C) 1982 D. E. Knuth, (C) 1996-2006 Han The Thanh
TeX is a trademark of the American Mathematical Society.

dvips -v

This is dvips(k) 5.991 Copyright 2011 Radical Eye Software (www.radicaleye.com)

convert --version

Version: ImageMagick 6.7.6-1 2012-03-14 Q16 http://www.imagemagick.org
Copyright: Copyright (C) 1999-2012 ImageMagick Studio LLC
Features: OpenMP

• Check if all programs are adequately configured on the path.
  On Windows the paths should be configured in the tomcat\webapps\cb\config\path.txt mentioned above, on Linux these commands should be on the system path. If everything looks fine, you can also try to put the applications' directories on Windows too.
• If you see an error on Windows such as: "Invalid Parameter - 120" in the log files, that means that the wrong convert.exe has been picked up by the system. Correct that by adding ImageMagick's path to path.txt.

Fixing ImageMagick authorization error (before 20.11-LTS Carmen)

In recent Ubuntu/Linux installations the ImageMagick library which is used to convert the Latex images to viewable images got a security fix which prevents the Latex/Math plugin from rendering the images properly.

This appears as either:

• If the Math or Latex plugin is NOT rendering and it fails with an error message like this:
  

  ImageMagick is not authorized to generate ps files

• or the UI displays this error message:
  
• or the cb.txt log file contains an error like the following then trying to render a Math or Latext plugin:
  

  ... codebeamer.utils.CommandExecutor     - error :<convert: not authorized `/tmp/cbmt5295041239142252236.ps' @ error/constitute.c/ ...

To fix this situation you need to enable the rendering of the PS (Postscipt) files by ImageMagick. That is typically done by editing the /etc/ImageMagick-6/policy.xml file and allow rendering the PS files here by editing this line:

So edit this file to contain this entry:

<policy domain="coder" rights="read/write" pattern="PS" />

For more information see: https://imagemagick.org/script/security-policy.php and https://www.kb.cert.org/vuls/id/332928