SWiM/installation

From MathWeb

This page describes how to install SWiM.

Download

The address is given on the main page. Users download the file linked there; developers can check out the project from the Subversion repository and build it using ant.

Prerequisites

Tomcat

SWiM needs to store some files in the file system. Be sure that you run Tomcat in a working directory that is writable by the user running Tomcat. (This also applies to IkeWiki.)

It is recommended to run Tomcat with an UTF-8 locale.

Increasing the Heap size

SWiM requires a lot of memory. It is strongly recommended to enlarge the Java heap to at least 384 MB. (The default is only 64 MB!) The permanent generation space should also be increased. To do so, add the following line to the script path/to/tomcat/bin/catalina.sh:

JAVA_OPTS="-Xmx384M -XX:PermSize=128m"

Note that on Mac OS X, using MacPorts, a customized script takes care of Tomcat, bypassing catalina.sh. I need to find out its path again… --Clange 18:46, 4 July 2007 (CEST)

PostgreSQL

If you do not install SWiM from scratch, but want to import an existing database dump, it might be necessary to first create both a user and a database swim (or whatever these names are). There is more than one way to do that; one way is using the createdb/createuser command line tools.

Developer's Tools

See SWiM/development

Browser

The most recent version of Firefox is always recommended, as I'm using that for testing. All Firefox versions ≥ 1.5 used to work before; Opera ≥ 9.5 may work as well. If you cannot properly view mathematical formulae, installing the MathML fonts for Mozilla may help. This got really easy with Firefox 3.5.

When you have installed all the fonts, earlier Firefox versions still gave you a warning message. In this case follow these instructions:

Run Firefox and enter "about:config"
click right, new -> string
Enter the name "font.mathfont-family"
Enter the value "CMSY10, CMEX10" (or, on Mac OS: "Math1, Math2, Math4, Symbol")
Close Firefox to save the changes

You can do the same with a “locate prefs.js”, and add the line

user_pref("font.mathfont-family", "CMSY10, CMEX10");

in the file.

See also the discussion about this topic. Thanks to Frédéric Wang for this hint :-)

Installation

The actual installation works in the same way as for IkeWiki. Just drop the SWiM.war file into the webapps directory of your Tomcat server; then go to http://url-of-tomcat/SWiM/ to proceed.

Installing more than one SWiM instance on one server

If you plan to set up more than one SWiM instance on a server, you should not use the default database name that is hard-coded into the installer (e.g. swim02). Here's how a second instance is installed:

Suppose the first instance uses database db1.
deploy the second WAR file (can be a link to the first one) and access the installer web interface
Now enter the database name for the second SWiM instance (e.g. db2).

If you already have a SWiM instance using the default database, replace step 2 by the following steps:

1. stop the PostgreSQL database server. (Otherwise the second instance would find the default database and think it's its own one.)
2. Deploy the WAR file, start the installer. The installer will be forced to look whether the default database exists but doesn't find it, as the database is offline. Therefore it asks you to enter a database name.
3. Before submitting the form, restart the PostgreSQL database server.

Setting up the Subversion client

Within limited constraints, SWiM can act as a client to a Subversion repository. The setup has to be done manually in the database. See this page for further information.

Setting up e-mail notifications

Every page has its own associated discussion forum – a feature inherited from IkeWiki. SWiM adds the possibility for users to receive e-mail notifications about new discussion posts. To enable this feature, you have to add a few entries to the configuration database table:

mail.smtp.host (required): an SMTP server via which the wiki sends mails
mail.from (required): the "From" address of these mails (can be an invalid one, such as noreply@domain.tld)
site.name (optional): the name of the wiki site, defaults to “SWiM“
site.url (optional): the base URL of the wiki site; the relative link to the wiki page in whose discussion forum a new message has posted is appended. (Sorry, there is currently no direct way of linking to discussion posts.)

Insert the values like this, while in the PostgreSQL client (see below):

insert into configuration(option, value) values('mail.smtp.host', 'mx.domain.tld');

Additional ontologies available for import (SWiM 0.1)

Importing the OMDoc document ontology (called “system ontology” in SWiM 0.1) is obligatory for SWiM.

Furthermore, it is strongly recommended to import the OpenMath standard content dictionaries (omstd) to get started, as they contain definitions of all common mathematical symbols, together with instructions how SWiM should present them. Compared to the OMDoc distribution, their names are prefixed with omstd-, as currently all OMDoc documents live in the same namespace (theory:). Although these content dictionaries define most of the mathematical symbols you will ever need, they neither provide formal definitions of these symbols (that would be suitable for automated theorem proving), nor do they make use of the power of the document ontology.

As an introduction to the ontology-powered featured, it is recommended to install the elementary algebra example (elalg), which is derived from the example in chapter 7 of the OMDoc book. The theories of groups and rings and similar concepts have been broken down to individual statements (using an extended version of the OMDoc DTD); for each page, SWiM recognizes a few semantic relations, which can be explored in the “references” box on the right.

The content dictionaries as well as the elementary algebra example both come with one summary wiki page, named OpenMathStandardContentDictionaries and ElementaryAlgebra, respectively. To easily access them, you may want to link them from the front page of the wiki.

Here's how that works in SWiM 0.1:

==Contents==

* [[ElementaryAlgebra|Elementary Algebra Demo]]
* [[OpenMathStandardContentDictionaries|OpenMath Standard Content Dictionaries]]

Troubleshooting

Problems during database setup

If the setup program fails during the database setup (which can occur when Tomcat has no write access to its working directory to store IkeWiki's settings file config.properties; see below), starting over only works when the SWiM database is deleted. To do so, log into PostgreSQL as administrator (root or postgres, depending on your PostgreSQL setup) and delete both the database and the role (i.e. the user) for SWiM:

# psql postgres root
Password for user root: 
Welcome to psql 8.1.8, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit
postgres=# drop database swim; drop role swim;
DROP DATABASE
DROP ROLE
postgres=# \q

Or even shorter:

# psql -c 'drop database swim; drop role swim;' postgres root

Note:

In SWiM 0.2, the default database and role name is swim02 to allow for a parallel installation with SWiM 0.1.
This how-to also applies to IkeWiki.

Problems storing the configuration file during setup (SWiM 0.1)

There is no real possibility to store a configuration file in the file system with Tomcat. If Tomcat wants to store it in the root directory of your system, you should create a file config.properties as well as a directory .ikewiki_index there and change its ownership to the user running Tomcat. OK, that's a dirty hack, but please tell me when you know of a better solution. --Clange 18:01, 4 July 2007 (CEST)

AccessControlException

If Tomcat can't find oscache-2.4.1.jar/META-INF/taglib.tld or issues an AccessControlException, try turning off Tomcat's security management. We are trying to find better solution but so far, this is the easy way around.

Importing more data

Importing just some OMDoc pages (SWiM 0.1)

To import additional documents, be it wiki pages or OMDoc documents, they need to be wrapped into an RDF/XML file. You can use the Perl script bin/doc2rdf4wiki.pl for that:

doc2rdf4wiki.pl -o omdoc-import.rdf *.omdoc summary.wiki

The above-mentioned omstd and elalg ontologies have been created with that tool. Mind the dependency XML::Writer! It can easily be installed with most package managers on Unix-like systems; watch out for packages named xml-writer or similar.

Importing a database dump

To entirely replace the database of your SWiM instance with a dump of another SWiM database or a previous backup of your own database, see the the PostgreSQL manual for instructions on how to import a dump. Beforehand, the database should be cleaned using the script database/clean.sql. Note that you might need to adapt the numbers of the tables generated by Jena beforehand so that they can be deleted. It may also be necessary to execute clean.sql twice when certain tables could not be deleted before others due to interdependencies.

For example, log into PostgreSQL as the user swim, and type:

\i clean.sql
\i swim.dump