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:
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:
In the following, it is assumed that a repository package has been used.
In this case, the following directories are created for Tomcat 6:
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
unzip -l TXM_Portal_x.x.zip
cp -r TXM_Portal_x.x/.TXMWEB/ /usr/share/tomcat6
total 4 drwxr-xr-x 5 tomcat6 tomcat6 4096 Jul 9 11:12 txm
dpkg -i TXM_x.x.x_Linux64.deb
TXM should be installed under:
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:
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:
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:
Restart the Tomcat service.
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
See the TXM portal admin manual for reference documentation: 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.
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”.
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
In some contexts (often) you need to enter a VPN before connecting to the server:
Connecting to server:
ssh -X <username>@<server IP>
ssh -X firstname.lastname@example.org
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 email@example.com:/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/ firstname.lastname@example.org:/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.
The tomcat application directory:
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:
The tomcat configuration directory:
The logs directory:
In the administrator's guide, you'll find:
Develop TXM WEB: