ActiveMath Installation How-tos

This book will contain installation instructions for the ActiveMath server.

For now, see the following disparate and not up-to-date resources:

and the pages below…

Installing/Updating ActiveMath from ActiveMath-SVN stable branch

This page describes how to install or update the ActiveMath server software from our central repository. This is done using Subversion (SVN for short).

This ActiveMath version is maintained by polx. It is mirrored at irregular intervals from the main CVS development tree after making sure that authoring tasks work.

Requirements

You will need the following:

a relatively fast machine with at least 512 Mb of RAM, and about 1 Gb of free disk space.
Java JDK 5 . On Windows, the environment variable JAVA_HOME must point to it. (here is how to do this). On Unix, the java command needs to be in the PATH.
a Subversion client. For Linux and MacOSX, use the official command-line client. For Windows, install TortoiseSVN or Subcommander.

First-time Installation of ActiveMath (Checkout)

Be sure to agree with the ActiveMath license: the D-FSL and the licenses of included libraries.

Create an empty directory where ActiveMath should be installed, for example on Windows C:\activemath\activemath-svn

To be safe, this path should not contain spaces or non-ASCII characters.

Use Subversion to check out ActiveMath into this empty directory. The repository location is:

http://klein.activemath.org/svn/activemath-svn

This will take some time since it downloads more than 400 Mb.

The same content can be downloaded as a single zip file of 420 Mb. It might be slightly outdated but an update will still be possible with this directory.

In order to complete the installation, you should now follow the installation instructions found in the file HowToInstall.html inside the READMEs directory. If you are on Windows, see Windows.html. Here, it will be sufficient to start InstallActivemath.bat from the bin directory (this needs a correct JAVA_HOME variable, see requirements). After that, start ActiveMath by double-clicking StartActivemath.bat.

Taking part to the community

It would be nice if you would register to this community-web-site, express your expectations as well as your experience in your profile, in your blog, as comments to this page, or as forum topic.

Also, if you start a content collection project, opening a page about it here is welcome. If you wish to make it under open-licenses (such as creative commons) we may offer basic subversion hosting which provides easier management and sharability.

Updating ActiveMath

From time to time, especially if you wish to receive fixes you know have been done, you will be requested to update the ActiveMath server.

With Subversion, you can simply “update” the existing installation:

make sure ActiveMath is not running.
If you are using using TortoiseSVN or another GUI client, you simply need to invoke the SVN update menu in the installation directory.
If you are using the command line version, cd to the activemath-svn directory, then invoke svn update. If you wish to know whether you have local changes, use svn status.

Methods to Integrate ActiveMath in a Larger Infrastructure

This chapter describes the various methods to deploy and install ActiveMath as part of a larger infrastructure, such as a school network, a firewall, or a learning management system.

Integrating ActiveMath within the Moodle LMS

ActiveMath can be integrated into a Moodle server by the usage of a proxy with the Moodle’s Apache. This configuration includes single-sign-on as well as special linking facilities. We explain the set-up here.

We suppose that you are running a Moodle server at your school, under the URL, http://moodle.myschool.net. We also suppose that this Moodle runs the Apache httpd server in versions 2.0 or above.

On Moodle’s Apache Side

You first need the proxy integration to be working so that http://moodle.myschool.net/ActiveMath2/ goes to your ActiveMath.

This is required so that the cookies that the browsers send to ActiveMath include the cookies sent to Moodle. ActiveMath uses them to read the personal profile of the user to create a new user, in case.

On ActiveMath’s Side

ActiveMath needs to be told where to look for the Moodle it becomes a slave of (that is, it will always obey to when checking for user registrations). Add the following lines to ActiveMath-individual.properties:

 app.sso.enabled=true
 app.sso.class=org.activemath.webapp.base.external.MoodleAuthenticationService
 app.sso.moodle.url=http://moodle.myschool.net/

then restart ActiveMath.

Now if you go to your Moodle, login there (not as guest!), then go to http://moodle.myschool.net/ActiveMath2 you will be recognized under the user-name you used in Moodle.

Linking with the ActiveMath Content Activity Module

Most URLs you visit in ActiveMath can be copied and pasted… but this task is a bit experimental and will fail in some conditions (notably the search tool).

The nice folks at HEG Fribourg are working on a Moodle Activity Module called ActiveMath Content Presentation. A course administrator will be able to use it to add a link to pages of a book or exercises of ActiveMath within Moodle.

The module is now available! Check this url: http://www.hefr.ch/projects/activemath/content/index.htm

Proxying ActiveMath on the back of Apache

Quite often, it is impossible for ActiveMath’s http port to be well accessible from the world. Firewalls, and other measures make the ActiveMath port 8080 inaccessible.

The Apache Web Server is the most used Web-server in the world, it is easy to deploy, is cross platform etc. This page explains how to use Apache’s mod_proxy to serve ActiveMath within the Apache space.

The basic idea:

only the Apache server runs, say, at http://myschool.net
you can run ActiveMath somewhere persistently inside the school (say on amserver at port 8080)
you configure the Apache to relay any request to http://myschool.net/ActiveMath2/ to go to your ActiveMath

Configuration on Apache side

The following configuration has been tested with Apache 2.0 but should work with further versions. Note Apache servers earlier than 2.0 do not ship per default with mod_proxy which needs to be configured and activated separately.

Add the following to your httpd.conf or to some virtual-host configuration:

    ProxyPass /ActiveMath2 http://amserver:8080/
    ProxyPassReverse /ActiveMath2 http://amserver:8080/

then restart your Apache. All requests on http://myschool.net/ActiveMath2/ will now be answered by the ActiveMath on amserver.

It is also possible to proxy the whole “/” within a virtual-host directive.

Configuration on ActiveMath side

Although the basic things will work with the above, there are times where ActiveMath needs to know the exact URL it is addressed through. This is the case of such advanced usages such as the Java Web Start descriptors of the assembly tool or ICmap.

Continuing the set-up above, add the following line to your ActiveMath-individual.properties:

 advertizedURL = http://myschool.net/ActiveMath2/

then restart ActiveMath. After this you are all set-up.

Translating the ActiveMath Server Software

This page under construction explains how to start the translation of the ActiveMath server with a new language. It should also be useful to correct or adapt the translations’ terms.

About

This page is an adaptation and enrichment of the README file in ActiveMath distribution under webapps/ActiveMath/i18n/I18n-Readme.txt.

This page does not cover the translation of content for which other documentation is expected in short.

Ingredients of the ActiveMath translation

The ActiveMath learning environment has the following source of textual messages which need to be adapted to each language:

each file inside webapps/ActiveMath may be variants internationalized which means that it exists in copies in different languages. In principle, this is only the help files.
the file may also be considered fully multilingual (e.g. the LeActiveMath logo), in which case, no translation is expected.
the file may also use phrases of the resource bundle but, itself, be multinational
finally, core content also comes along each ActiveMath and is used by most other content collection. These are mostly symbols and notations and should be translated as well.

Translators’ work

First, an enrichment of the configuration will be needed in order to introduce the language, even if missing all translations.

Translators should then edit the phrases file and compile.

Translators are, then, expected to go through all the directories of webapps/ActiveMath to check if each file is fully-multilingual (or uses phrases, in the case of .vm files, as can be seen with the usage of the #phrase macro), or if it has variants (such as next_de.gif which is a variant of next.gif).

Finally, translators should edit each of the .omdoc files in omdoc1/cd/ to add the translations.

Encoding warning

It has been a convention that all text files in ActiveMath are encoded using the utf-8 character set, please avoid imperatively to use editors that do not support this encoding (such as many installations of emacs or notepad).

Introducing a new language

Find the ISO language code for your language (see the list)
Add an entry for your language code to conf/ActiveMath.properties. This is done by adding a new property

        messages.defaultLanguage.i=XX'

where i is a number not already used by the other languages, and XX is your language code (eg. `messages.defaultLanguage.4=cn`). ### The Phrase file - For your language XX, create a file ‘i18n/phrases_XX.properties’, which must be in UTF-8. Start with an existing phrase file and use it as a template. The phrase file starts with a comment that contains more information on how to encode phrases. - Each phrase file starts with a list of language names. Add your language to *each* of the phrase files. The name of your language must be written in the language itself (“Deutsch”, not “German”). Here is the current list:

    language.de=Deutsch
    language.en=English
    language.fr=Français
    language.es=Español
    language.it=Italiano
    language.nl=Nederlands
    language.ru=Русский
    language.zh=中文

Variants Translation

The following files, at least, need to be translated by adding a variant:

The help files are found in help/. Here, the text is directly found in the Velocity files (no phrases). To translate, copy the English version of each file to ‘file_XX.vm’ and translate that. Chances are that the English help is the most up to date, so use it as a reference.
several other files have already variants and you should introduce yours as well
crawling through the skins directory is probably not useful unless specifically requested.

Testing

After changing a phrase file, you need to invoke ant i18n from the ActiveMath bin directory. The build script will convert each file i18n/*.properties into an ASCII-encoded file in i18n/ascii with the same name, which can be loaded by Java. (For details, see the JDK doc for the native2ascii tool.)

Unfortunately, you currently have to restart ActiveMath for the changes to take effect.

For testing, you can switch the user’s language in the menu “My profile / My user data”).
To test a single page in several languages, a trick is to append the parameter ‘&lang=xx’ to the URL.
Changes to Velocity files are visible immediately, just reload the page in your browser.
When you have tested, check in your changes. Don’t forget to add the new files to CVS first. If you are missing CVS commit rights, please get in touch with ActiveMath developers.

Adding new text to the GUI

When adding a new key to the GUI (because you are programming a new thingie) or changing the semantic of a message, please make sure to impact all properties files. You fill with correct values for the files you can. For the others, you fill them commented out and the word MISSING as follows:

# MISSING: register.beHappy = Let's be happy!

This way, localizers (which can be really external persons) can browse seasonally through the properties file of their language and find all the “MISSING”! Also, they see the english text and have a clue about what the phrase is.

How to remove a language

It sounds dumb to do so but it’s meaningful if you are writing skins which, typically, will only be available in context where only one or two languages make sense and is writable.

You need, for this, to overwrite the properties declaring the language making it empty. As follow, to remove french in the current ActiveMath, add the following in ActiveMath-indvidiual.properties:

  messages.defaultLanguage.3      =

(in other configuration files, which ActiveMath-individual.properties overwrites, the value is messages.defaultLanguage.3 = fr)

Translating core content

TODO: describe the task here, which involves the same OMDoc translation task for the .omdoc files in omdoc1/cd.

Adding a language to the search tool

The search tool needs special care for new languages and may fail to work with an added language. This is because several procedures are made to enhance the retrieval quality and they depend on each language.

Note that the search tool only searches the current language (different opinions welcome) unless otherwise indicated. For now, if you are lucky, you will find your content. In any case, an investigation is required to find the two following ingredients:

a stemmer or analyzer for the Lucene retrieval library for the new language is needed. A stemmer is little procedure which converts words to their stem, allowing chevaux and cheval to be found at the same time. The snowball project of Martin Porter is probably the best tool to approach this.
a phonetic tokenizer is also needed: this tokenizer converts words to phonetic tokens in such a way that two words that have the same phonetics become the same token. Classical algorithm include Soundex and Metaphone, we are using the latter for English, German, and Spanish for now.

One you have found approaches to this, which might to say english stemming and phonetic tokenization is ok for now, you should please contact the developers so that we can enable this for the new language… it will require development on our part though this may be really small.