Install a TXM Portal / Installer un portail TXM

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

System Requirements

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

Configuring Tomcat

Methods

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 and tomcat6-admin that contains the tomcat Web manager)

Installation directories

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.

Environment

You should not need to configure the CATALINA_HOME variable.

Security

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.

Deployment with Tomcat7: configure WAR file size

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.

Starting and Stopping Tomcat

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

Testing Tomcat

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

Downloading the TXM software

Installing the TXM portal

  • 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 version just installed to complete its installation process, the TXM local directories should be created under:

/home/<user>/TXM

If your server does not include a desktop environment (headless server configuration), you need to enable X11 forwarding or tunneling (with -X option in ssh) between the server and the X11 server (e.g.: X11 on Linux, XQuartz on Mac OS X, Xming or Cygwin/X on MS Windows) of the client machine. TXM Graphical User Interface will then be displayed and interactive on the client machine screen.

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

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

Configuring the TXM portal

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/

You can copy all the corresponding binaries and libraries paths set in the “install.prefs” file of the TXM desktop installation directory.

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.

Encrypting the Tomcat password

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.

Deploying the TXM portal in Tomcat

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

If you cannot or don't want to use a Web browser to access the Tomcat manager, you can deploy the 'txm.war' on the server with the following shell command lines:

$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

Validating the running TXM portal

  • open your new portal address: http://host:8080/txm
  • verify that you can see and use the two DISCOURS and GRAAL sample corpora. You have all the access rights to analyze and access them but you don't have the 'Subcorpus' and 'Partition' building access rights
  • verify that when connection with the 'demo' login you get full access rights on them
  • verify that the 'admin' login (with the configured password) gives access to the admin interface : add corpus, create profiles, create user accounts, associate profile to account, etc…

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

Troubleshooting

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

JVM memory configuration

By default the allocated memory of the JVM is 128MB. If you have some Java Heap Space exceptions in tomcat logs when using the portal you can increase the memory for tomcat service by editing the file /etc/init.d/tomcat6 and adding this line:

JAVA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=1024m"

as first line of the catalina_sh() function, before this line:

JAVA_OPTS="$(echo $JAVA_OPTS | sed 's/\"/\\\"/g')"

After restarting the portal with:

sudo service tomcat6 restart

you can check that the JVM arguments has been modified in the Tomcat manager, in the tab “Server status”.

Limited permission

According to your user account you may need to change permissions of some directories to edit the files described in this tutorial, you can change the permissions with, for example:

sudo chown -hR <user> /var/lib/tomcat6

Don't forget to restore the permissions after having edited the files or the portal won't run:

sudo chown -hR tomcat6 /var/lib/tomcat6

Accessing through a VPN

In some contexts (often) you need to enter a VPN before connecting to the server:

  • connect to the VPN with your system tools (typically a standard OpenVPN), eg. Linux: Réseau > Connexions VPN > <VPN name>
  • or launch a specific VPN client from command line, eg. Linux: sudo ./fortisslvpn.sh
    • set gateway, login, password

Working through SSH

Connecting to server:

ssh -X <username>@<server IP>

eg.:

ssh -X txm-user@xxx.20.53.62

Starting XFCE:

startxfce4

Copying a file from client to server:

scp <file> <username>@<server IP>:<destination>

Example to copy a TXM binary corpora to server:

scp /home/user/CORPORA1.zip user@xxx.20.53.62:/home/user

Copying a directory, by adding ”-rp” options:

Example to update some facs edition HTML files from a VMWare shared directory:

scp -rp /mnt/hgfs/___shared_for_vm/facs/ user@xxx.20.53.62:/usr/share/tomcat6/.TXMWEB/txm/corpora/CORPUS1/HTML/CORPUS1/

See also rsync command that manage the version of the files and only copy the files if they have changed.

Directories description

The tomcat application directory:

/usr/share/tomcat6/

This directory also contains the TXM user directory with corpora, etc. and portal configuration files:

/usr/share/tomcat6/.TXMWEB
/usr/share/tomcat6/.TXMWEB/bfm/txmweb.conf            // main portal configuration file
/usr/share/tomcat6/.TXMWEB/bfm/textometrie.properties // toolbox configuration file

The tomcat published space accessible through HTTP network:

/var/lib/tomcat6/webapps/

The tomcat configuration directory:

/etc/tomcat6/

The logs directory:

/var/log/tomcat6/

FURTHER DOCUMENTATION

FURTHER SETUP STEPS

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

FURTHER DEVELOPMENT DOCUMENTATION

public/install_a_txm_portal.txt · Dernière modification: 2017/02/08 10:55 par slh@ens-lyon.fr