Install a TXM Portal / Installer un portail TXM

Thanks: Giancarlo Luxardo for helping us writing this tutorial and for testing TXM portal

The minimum requirements for installing and running the TXM portal version 0.6.1 are as follows:

• Linux server (the portal is known to run on Ubuntu Server 12.04 LTS, other distributions may also be used)
• 32-bit or 64-bit architecture
• at least 2 GB of memory available to every instance of the TXM portal running on the server
• at least 50 GB of available disk space
• Java Runtime Environment version 6 or later (OpenJDK recommended)
• Tomcat version 6 or later

You need to have root access on this machine.

The Java architecture may be checked by one of the following commands:

java -version
update-java-alternatives -l

There are at least two methods to download and install Tomcat:

• using a binary distribution provided by the Apache Web site
• using a repository package (for Tomcat 6, the useful Debian packages are: tomcat6, tomcat6-admin)

In the following, it is assumed that a repository package has been used.

In this case, the following directories are created for Tomcat 6:

• /usr/share/tomcat6/
• /etc/tomcat6/
• /var/lib/tomcat6/
• /var/log/tomcat6/

The owner of these directories is the tomcat6 user.

You should not need to configure the CATALINA_HOME variable.

Add the folowing lines between the '<tomcat-users>' and '</tomcat-users>' lines in the '/etc/tomcat6/tomcat-users.xml' file:

<role rolename="manager-gui"/>
<role rolename="manager-status"/>
<user username="admin" password="password" roles="manager-gui,manager-status"/>

The Tomcat password is initially in plain text. It will be encrypted in a next step.

If you are using Tomcat 7, edit the '$TOMCAT7/webapps/manager/WEB-INF/web.xml' file as follows:

<multipart-config>
<max-request-size>524288000</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>

Throughout the rest of the document it is assumed that Tomcat 6 is used.

Tomcat is normally configured to start automatically at boot time.

Tomcat 6 may be started and stopped using the tomcat service:

service tomcat6 start
service tomcat6 stop
service tomcat6 restart

Tomcat is by default configured to run on the 8080 port.

According to your host name (possibly 'localhost'), open the following URL in a web browser: http://localhost:8080

You should see the following message:

It works !

If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!

If you have installed the Tomcat admin package, you should also see the Tomcat manager: http://localhost:8080/manager/html

• Download the latest TXM portal version from: http://sourceforge.net/projects/txm/files/software/TXM%20portal
  (the same archive is valid for 32-bit and 64-bit architectures)
• Download the latest TXM desktop version from: http://sourceforge.net/projects/txm/files/software/TXM
  (in this case choose the 32-bit or 64-bit version specific to your server architecture)

• Decompress the TXM portal archive to a local directory:

  unzip -l TXM_Portal_x.x.zip

• Copy the '.TXMWEB' directory, found under this local directory, to the Tomcat home directory:

  cp -r TXM_Portal_x.x/.TXMWEB/ /usr/share/tomcat6 

• Make sure that the tomcat6 user owns the '.TXMWEB' directory, e.g.:
  • chown -R tomcat6.tomcat6 .TXMWEB/
  • ls -l /usr/share/tomcat6/.TXMWEB/

    total 4
    drwxr-xr-x 5 tomcat6 tomcat6 4096 Jul 9 11:12 txm

• Install the TXM desktop (this step is required in order to install the CWB search engine and the R statistics engine), e.g.:

  dpkg -i TXM_x.x.x_Linux64.deb

TXM should be installed under:

/usr/lib/TXM

Run the TXM desktop to complete the installation process, the TXM local directories should be created under:

/home/<user>/TXM

If your Linux system does not include a desktop environment, you need to enable X11 forwarding (-X option with ssh) to an X11 server on a client machine (e.g.: XQuartz on the Mac OS X, Cygwin/X on Microsoft Windows).

Make sure that the subdirectories are accessible for read & write rights to the tomcat6 group:

• /usr/lib/TXM
• /home/<user>/TXM

The TXM configuration is done with parameters files. They are stored in the '/usr/share/tomcat6/.TXMWEB/txm/' directory. Configure TXM Toolbox parameters in the 'textometrie.properties' file[modifier]

Make sure that the following parameters are valid:

cqi_server_path_to_cqplib=/usr/lib/TXM/cwb/bin/
cqi_server_path_to_executable=/usr/lib/TXM/cwb/bin/cqpserver
cqi_server_path_to_init_file=/usr/lib/TXM/cwb/cqpserver.init
cqi_server_path_to_registry=/usr/share/tomcat6/.TXMWEB/txm/registry/
r_path_to_executable=/usr/bin/R
workspace_location=/usr/share/tomcat6/.TXMWEB/txm/workspaces/default.xml
user_txm_home=/usr/share/tomcat6/.TXMWEB/txm/
log_directory=/usr/share/tomcat6/.TXMWEB/txm/logs/

Then, replace the <user> with your login:

install_dir=/home/<user>/TXM

Configure TXM portal parameters in the 'txmweb.conf' file:

txm.properties=/usr/share/tomcat6/.TXMWEB/txm/textometrie.properties
default_admin_pass=<encrypted-password>
portal_address=http://<host>:8080/txm/
mail.protocol=smtp
mail.host=<my.smtp.server>
mail.user=<my.user>
mail.default.from=<my.user.from@mail>
mail.default.reply=<my.user.reply@mail>
mail.contact=<my.user@mail>

You need to define the TXM administrator password. It must be encrypted with the MD5 algorithm.

You can use the 'makePassword.jar' file, found in the TXM portal archive, to generate the password, e.g.:

java -jar makePassword.jar <mypassword>

Note: for other configuration parameters, please refer to the TXM portal admin manual.

It is recommended to encrypt the password previously written in the '/etc/tomcat6/tomcat-users.xml' file.

Run once again the 'makePassword.jar' file:

java -jar makePassword.jar <tomcat-password>

Replace the previous password with the result.

Edit the '/etc/tomcat6/server.xml' file, look for the <Realm> element and add the following attribute:

digest="md5"

Restart the Tomcat service.

• Connect to Tomcat manager with http://localhost:8080/manager/html URL
• In the “upload” field put the path to the 'txm.war' file
• Clic “Deploy”. A message at the top of the page will confirm success or failure.

If you cannot use a Web browser, you can deploy the 'txm.war' on the server with the following procedure:

$MANAGERURL = <host>:8080/manager/html
$APPNAME = txm
$WARPATH = <path-to-the war-file>

wget "$MANAGERURL/undeploy?path=/$APPNAME" -O – -q
wget "$MANAGERURL/deploy?deployPath=/$APPNAME&deployConfig=&deployWar=file:$WARPATH" -O – -q

In a Web browser, go to: http://host:8080/txm

You can now see and use the sample corpora (DISCOURS, GRAAL). You have all the rights to analyze/access them but not the 'subcorpus' and 'partition' building rights.

The sample 'demo' account will give you full rights on them.

The 'admin' account (with the configured password) gives access to the admin interface : add corpus, create profiles, create account, associate profile to account, etc…

See the TXM portal admin manual : https://txm.svn.sourceforge.net/svnroot/txm/trunk/doc

If an error message such as “TBX: not initialized” or “Could not initialize Toolbox” appears, check the Tomcat logs for further diagnostic information.

• TXM portal administrator guide (in French): https://txm.svn.sourceforge.net/svnroot/txm/trunk/doc/Manuel%20de%20reference%20TXMWEB%20Admin%200.6.1_FR.odt
• TXM documentation directory: https://txm.svn.sourceforge.net/svnroot/txm/trunk/doc

In the administrator's guide, you'll find:

• to add new users: see section 2.2a
• to personalize user profiles: see section 2.4.5
• to add a new corpus: see section 1.2
• to personalize HTML pages: see section 1.6
• to enable and personalize portal mails: see section 1.8
• to enable user subscription: see section 2.3.4
• to add a TIGERSearch corpus index: (to be documented)
• enable R commands: see wiki

Develop TXM WEB:

• install DEVELOPMENT ENVIRONMENT: https://sourceforge.net/apps/mediawiki/txm/index.php?title=Build_the_toolbox_or_the_application#TXM-WEB_:_GWT_web_application
• developer guide: https://txm.svn.sourceforge.net/svnroot/txm/trunk/doc/Manuel%20de%20reference%20TXMWEB%20Dev%200.3_FR.odt
• TXM WEB deploy: TXMWEB: Test War
• develop the TXM Toolbox: https://sourceforge.net/apps/mediawiki/txm/index.php?title=Build_the_toolbox_or_the_application#Toolbox_:_the_core