TMAJ Server Setup

About this document

This document explains how to setup a TMAJ server.  This is the wrong page if all you need to do is install a client.  Once you have performed the steps on this page, you will be able to customize TMAJ and it source code for your own needs.  These instructions will work for both Windows and Unix.
         

Step 1: Download TMAJ

  1. Download the latest version of TMAJ.   You will find the latest version on sourceforge.net. The URL is: http://sourceforge.net/projects/tmaj/
  2. Unzip the zip file.  If you don't have a zip file utility, and you're using Windows, you may want to choose 7Zip (free) or WinZip (pay).  Windows XP comes with support for zip files.  If you're using a UNIX system, you can use the gunzip command.

Step 2: Install Java 6 JDK

  1. Download and install the Java 6 JDK You should get the latest version of the JDK.  Currently the latest version is "JDK 6 Update 24".  Any versions later than this version should work as well.
    • Version 6 is required. You must have Java 6 for TMAJ to work.  It is not compatible with Java 1.4 and Java 5.
    • The JDK is required.  You need to download the JDK (Java Development Kit)  and NOT the JRE (Java Runtime Environment.)  The JDK actually includes the JRE.  The Java Runtime Environment allows you to run Java applications, while the JDK allows users to compile and run Java applications.   During this setup procedure you will actually compile TMAJ, and thus you need the JDK.
    • Windows: If you're using Windows, you can use this link to download the JDK.  All you need to do is double click the .exe file you downloaded.  You may use all the default options on installation.
    • Ubuntu: If you're using Ubuntu Linux, you can simply run this command to download and install java.
      sudo apt-get install sun-java6-bin sun-java6-jre sun-java6-jdk
  2. Verify Java was installed properly (Optional).   You can do this by going to any site where there is a Java application and seeing if you can run it.  For example, try one of these links to verify that Java is working on your computer:
    http://bui2.win.ad.jhu.edu:8080/tmaj_jhu_production/client/tmaj_jhu_production.jnlp
    http://www.jgoodies.com/download/jdiskreport/jdiskreport.jnlp
  3. Verify Java was installed properly (Optional).  Another test is verifying that the javac (Java Compile) command is installed.  That is, simply open a command prompt and type javac.  For this to work in windows, you will need to have added javac.exe to your path. 

Step 3: Install Apache Tomcat

  1. Download Apache Tomcat.  You should download the latest version of Tomcat 7.  You can use Tomcat 6 or earlier, but there is a minor modification you need to make to a build variable if you do. (See below) You can download the binary copy.  You don't need the source copy.
    • Windows: You should download the "Windows Service Installer" -- it's a .exe file that's relatively simple to install.
    • Ubuntu: You can download the .tar.gz Core file from one of the mirrors.  For example:
      wget http://www.eng.lsu.edu/mirrors/apache/tomcat/tomcat-6/v6.0.20/bin/apache-tomcat-6.0.20.tar.gz
  2. Install Tomcat.  You must have installed Java before you can install Tomcat (the last step).
    • Windows:  If you're using Windows, it is as simple as double-clicking on the .exe file you just downloaded and following the options below
      • Choose Components Screen:
        [X] Service.  (Make sure the "Service" box is checked so that Tomcat may be run as a Windows service).
        [  ] Native.  You may leave the "Native" checkbox unchecked.
        It is up to you whether or not you want to install the Start Menu Items, the documentation, or the examples.  All of them are optional.
      • Configuration Screen
        These are the default values in the TMAJ config file, but you may use different ones.  You should use a different password, but make sure you remember the password you used for Tomcat because you will need it later.
            Port: 8080
            Username: admin
            Password: tomcat555
            Roles: manager-script
        Any of these values may be changed later.  You should use a different password.  Apache Tomcat puts these values in the tomcat-users.xml file.  If you want to change them later, modify them in this file and then restart Tomcat (you must restart Tomcat in order for the password change to take effect.) If you use Tomcat 6, the role should be "manager" and not "manager-script"
    • Ubuntu: You may follow the links here for help installing Tomcat: http://www.howtogeek.com/howto/linux/installing-tomcat-6-on-ubuntu/
      • tar xvzf apache-tomcat-6.0.20.tar.gz
      • sudo mv apache-tomcat-6.0.20 /usr/local/tomcat
      • nano ~/.bashrc
        Add the following line:
        export JAVA_HOME=/usr/lib/jvm/java-6-sun
      • sudo /usr/local/tomcat/bin/startup.sh
  3. Verify Tomcat Installation (Optional).  Point your web-browser (Internet Explorer, Firefox, etc)  to your main Tomcat webpage.
    • The URL will be something like:  http://127.0.0.1:8080/
      • The port number will be different if you didn't use port 8080 in the last step.
    • You may want to verify that Tomcat can be accessed from a different machine, since any tmaj clients will be connecting to TMAJ from other machines.
      • To test this, just replace the 127.0.0.1 with your server machine's ip address or hostname.  So for example, use the URL: http://host.mysite.com:8080/
    • If the Tomcat installation was a success, you should get to a webpage saying:
      "If you're seeing this page via a web browser, it means you've setup Tomcat successfully."
    • If for some reason you cannot access the page, make sure you have the service started.

Step 4: Install Ant

Windows:
  1. Download Apache Ant.  There will be a zip file of ant that you can download that looks something like: apache-ant-1.8.2-bin.zip.  If you are installing an operating system other than Windows, please check the Ant website for the instructions on how to install Ant for your operating system.
  2. To install Ant on Windows, simply unzip the file you downloaded into C:\Program Files
    Your directory structure will look something like:
    C:\Program Files\Ant
    --bin/
    --docs/
    --etc/pwd
    --lib/
  3. Add the ant\bin directory to the Path variable.  Path is a Windows Environment Variable.  Google for Windows Environment Variables if you do not know how to set them.  The bin directory would be:
    C:\Program Files\Ant\bin
    (Make sure that this directory actually exisits.  You may have installed ant somewhere else.)
  4. Add the java\bin directory to the path variable. The JAVA_HOME\bin directory will look something like:
    C:\Program Files\Java\jdk1.6.0_24\bin
    (Again, note the directory above actually exists. You may have installed a different version of Java.)
    After you have added both the ant\bin directory and the java\bin directory, the path variable will end up looking something like this:
    C:\Program Files\Ant\bin;C:\Program Files\Java\jdk1.6.0_24\bin;%SystemRoot%\system32;
    The underlined portion is the part of the path that you added. Note that we add the bin directories at the beginning of the path and not at the end.
  5. Add JAVA_HOME environment variable.  Set the JAVA_HOME environment variable to the location of the Java Development Kit.  It should be somewhere like:
    C:\Program Files\Java\jdk1.6.0_24
  6. Add the ANT_HOME environment variable.  Set the ANT_HOME environment variable to the location where you installed ant.  It should be somewhere like:
    C:\Program Files\Ant
Ubuntu:
  1. Make sure that the JAVA_HOME environment variable has been set.  For example, you can add it to the end of your ~/.bashrc file:
    export JAVA_HOME=/usr/lib/jvm/java-6-sun
  2. sudo apt-get install ant
Verify:
  1. Verify Ant Installation (Optional). 
    Open a command prompt (start button > run > type in cmd > hit enter) and go to the directory where you unzipped the tmaj code.  You should see a file called build.xml.
    Type in:
    ant init
    You should get a Build Successful message.
    • If you get an error that says: 'ant' is not recognized as an internal or external command, operable program or batch file. it means Windows can't find the ant.bat file.  You probably didn't set the path environment variable correctly.
    • If you get an error that says: Unable to locate tools.jar, it means you probably didn't set the JAVA_HOME environment variable properly.
    • If you get an error that says 'java' is not recognized as an internal or external command, operable program or batch file. it means Windows can't find the java.exe file.  You probably didn't set the path environement variable correctly.  Also, remember that windows has a java.exe file in C:\windows\system32 directory, which is in the path. You should make sure that the java\bin directory is listed first in the path, and not at the end.

Step 5: Setup the Database

  1. Determine the database you want to use.  We recommend and use MySQL. MySQL is open source (free) and easy to install.   Tmaj is designed to be compatible with multiple databases, so if you are trying to use something else like PostgreSQL, it would not be difficult to add this yourself or you may wish to contact the developers.  The rest of this step will be specific to the database you choose.
    Currently, TMAJ supports the following databases:
    • MySQL (tested on MySQL 4.0 & 5.0 & 5.1 & 5.5)
    • Microsoft SQL Server (tested on SQL Server 2005)
    • Oracle:   (tested on Oracle 8i and Oracle 10G)
    • Sybase SQL Anywhere (tested on SQL Anywhere 8 and 9)
  2. Get the Install File(s) for the database. 
    • Microsoft SQL Anywhere
    • MySQL: We recommend the latest GA (generally available) version, which is currently version 5.5.  There are later versions that are beta-versions, which are probably okay.  You will only need the minimum installation (For windows this would be "Windows Essentials".) 
    • Oracle
    • Sybase SQL Anywhere: You may use SQL Anywhere version 8 or later.  The current version is 11.  You will have to register with Sybase to download this copy.  Registration is free.  If you get the trial version of SQL Anywhere, you have 60 days before it expires.
      For the installation, use all the default options.  
  3. Install the Database.  Tmaj doesn't use any procedures or triggers, so you won't need to have any special options.  You should generally be able to use all the default options for your install. Make sure to use a different password and remember what values you choose in the database setup process.  (Later we will put these in a config file.)  During the database install, you will be prompted for a database username and password.  The default values used in the tmaj config file are below.  You should use a different password.  (Also for security reasons, you might want to have a different non-admin user that can only access the TMAJ database.)
    username: root
    password: db555
  4. Install a Database Front-end GUI (optional).  To make things easier you may wish to install a database front-end GUI. 

    Windows: If you are using MySQL, A possible choice would be "MySQL Workbench" which is also available on the MySQL website.

    Ubuntu: Go to the Synaptic Package Manager and click on "MySQL Administrator" and "MySQL Query Browser", or:
    sudo apt-get install mysql-admin
    sudo apt-get install mysql-query-browser
  5. Go to the database's client.  This is where you will create the database.  It may be a GUI or a text-interface. 

    Windows:
    start button >> All Programs >> MySQL >> MySQL Server 5.1 >> MySQL Command Line Client >> enter password: db555

    Ubuntu:
    sudo mysql --user=root --password=db555

  6. Create a new database
    Name the database: tmaj   (this is merely the default in the config file.  You can name the database another name.)
    create database tmaj;
  7. Create a database account (username) that can access the TMAJ database (Optional)
    Of course you can always use the root account, but for security reasons you might want to create a custom account just for TMAJ.  You will later need to specify this account's username and password in a config file.
  8. Go into the new database. If you're using MySQL, the command is:
    use tmaj;
  9. Create the Tables in the Database Schema
    When you downloaded the TMAJ zip file, it came with a SQL file that will create the tables and foreign keys in your tmaj database.  The SQL file you use will depend on which database you choose.  For example, if you are using a MySQL database, run the schema_mysql.sql on your database.  The appropriate files are listed below.
    • Microsoft SQL Server: schema_sql_server.sql 
    • MySQL: schema_mysql.sql
    • Oracle: schema_oracle.sql
    • Sybase SQL Anywhere: schema_sybase.sql
    If you're using MySQL, the command to use (while in MySQL Command Line Client) is:
    source C:\temp\tmaj_installation\sites\Default\miscellaneous\schema_mysql.sql
  10. Verify Database Installation (Optional).  You may want to try running a query like:
    SELECT * FROM Users;
    This will verify that the schema creation worked.  (Of course, no rows will be returned, but you shouldn't get an error.)

Step 6: Setup the Config Directory

For all config files: Make sure none of your directories have slashes or accidental spaces at the end.  (The only exception is WebserverURL variable, which has a slash at the end.)  Always use forward slashes (/) , even in Windows.  You can skip all the verification steps.  They are there in case you run into problems and you want to retrace your steps.

  1. Locate the config directory.  You will find it as a top-level directory whereever you unzipped the tmaj download.
  2. Get the IP Address or Hostname of your TMAJ Server. 
    This may be done by opening a dos prompt and typing in
    ipconfig
  3. client.properties:
    1. ServletURL: You need to change the ipaddress to the public ip address of the tomcat server.  If your tomcat service does not run on port 8080, change the port as well.  For example, your servletURL might be: http://bui2.win.ad.jhu.edu:8080/tmaj/servlet/TMAJ_Server.srv
    2. Change the Site variable to whatever the name of your site is.  For example, your site might be "Cleveland Clinic"
    3. Verify: Verify that you can actually connect with a web browser to the base of the ServletURL  It will be something like "http://bui.win.ad.jhu.edu:8080".  This will be the base of where tomcat is installed.  Don't try to connect to the entire ServletURL which will be something like "http://bui2.win.ad.jhu.edu:8080/tmaj/servlet/TMAJ_Server.srv" as that will fail until the "ant push" step is done. You might want to try this from another computer besides to server to make sure you can actually connect.
  4. database.properties: Set the values in database.properties to the appropriate values.
    1. db_user and db_pass: This the the username and password used to log on to the database.  In Sybase the default username is dba and the default password is sql.  Note this has nothing to do with the tmaj usernames and passwords that you will give out to tmaj users.
    2. db_type: In addition, you must set the database type to the appropriate type (For example, Oracle or MySQL.) 
    3. ip_address: Generally, the database runs on the same machine as the Tomcat server.  If this is the case, you can leave the database IP address as 127.0.0.1. This is because the client never directly accesses the database -- all database accesses are done through the Tomcat application.)
    4. port: Make sure you know what port you database is running on.  For example, by default, my sql runs on 3306.   
    5. db_name: This is the name of your database. By default this is tmaj.
    6. testSql: This is a sql statement that is run to test the connection is valid.  This sql statement should run very quickly for performance.  You should not need to change this.
    7. Verify #1: Verify that the database username and password you wrote in the config file actually work by logging on to your database.  How you log on to your database will vary depending on the database you choose.
    8. Verify #2: Verify you can connect to the database ip address and port using telnet.  Go to the machine that is running Tomcat.  Then enter the command:
      telnet ip_address port
      for example:
      telnet 127.0.0.1 3306
      If you get some strange characters printed, the test is successful.
      If you get a "connect failed message", it means that the test failed and TMAJ won't be able to connect to your database using the IP address and port you specified in database.properties.
  5. compile.properties:
    1. tomcat.manager.username & tomcat.manager.password: These are the passwords used to log on to tomcat.  These have nothing to do with the database username and password nor the tmaj usernames and passwords that you will assign to users.   If you need to change these values, they can be found in the tomcat-users.xml file.  You must restart Tomcat after changing them.
      Windows: These username nad password was created when you installed tomcat.  You shouldn't need to do anything (except remember the username & password, which are as specified unless you changed them.)
      Ubuntu: You should add a user in the tomcat-users.xml file such as:
      <user username="admin" password="tomcat555" roles="manager-script"/>   (make sure this is not commented out)
      Note: If you use Tomcat 6 or earlier, the role should be just "manager". You must restart Tomcat after adding this user.  You may use the shutdown.sh script to shutdown Tomcat.
    2. tomcat.home_dir: 
      Windows: this will be something like: C:/Program Files/Apache Software Foundation/Tomcat 7.0/
      Ubuntu: This value should be something like: /usr/local/tomcat/
      Unix: The directory in Unix operating systems will vary.    In Unix, the Tomcat installation is spread out over several directories so locating the home directory can be somewhat confusing.  The home directory for Tomcat will contain a directory called webapps.   In turn, the webapps directory will have a directory called ROOT.  This should help you locate the home directory.  In our example, the webapps directory would be located here: "C:/Program Files/Apache Software Foundation/Tomcat 7.0/webapps" .   After you perform the "ant push" in a later step in these instructions, you will see a tmaj directory in the webapps directory.   The tomcat directory structure appears below.
              Notes on the Tomcat Directory Structure:
      --- Tomcat_Home_Directory/
      ------ webapps/
      ------------ ROOT/ (Tomcat installs this by default.  When you go to the http://localhost:8080 in a web browser, these are the files that Tomcat displays)
      ------------ tmaj/  (this directory is created later after the "ant push" step. )
      ------------------ WEB-INF/ (the "ant push" puts server code here)
    3. tomcat.webAppName: You should not need to change this.  The default is tmaj.
    4. tomcat.manager.url: The default is http://127.0.0.1:8080/manager/text and you should not need to change this, unless you installed tomcat on a port other than 8080.  This assumes that you run the ant script on the same machine that the tmaj server is installed, which is why the "127.0.0.1" can be left as is.
      Note: If you installed Tomcat 6 or earlier, you will need to to change this from "http://127.0.0.1:8080/manager/text" (Tomcat 7) to simply "http://127.0.0.1:8080/manager" (Tomcat 6 or earlier). If you use Tomcat 7, you won't need to make any modification here.
    5. Verify #1: Get the base of your tomcat.manager.url variable.  It will be the base of tomcat, which as mentioned before, will be something like "http://127.0.0.1:8080".  Open that address with a web-browser, and then click on the "Tomcat Manager" link.  Verify that the username and password you gave for the tomcat.manager.username and tomcat.manager.password actually work.
    6. Verify #2: Verify that the tomcat.home_dir contains a subdirectory called webapps, and that the webapps directory contains a subdirectory called ROOT.
    7. Verify #3: Verify that the ServletURL for Tomcat and the tomcat home directory are in sync.  Make a conspicuous modification to the file tomcat.home_dir/webapps/ROOT/RELEASE-NOTES.txt.  Next, go to the servletURL base (e.g. http://127.0.0.1:8080/RELEASE-NOTES.txt).  Your modification should show up.
  6. server.properties:
    1. Images_Root_Directory: This is the directory where TMAJ will put image files.  The images are not stored into the database.  You should never need to modify this directory manually.  This directory must be readable and writable by the tomcat service.   The default is:
      C:/tmaj_images. 
      You will need to manually create this directory. 

      Windows:
      mkdir C:\tmaj_images

      Ubuntu:
      sudo mkdir /var/tmaj_images

  7. tmaj.jnlp
    1.  codebase: By default this is set as "http://127.0.0.1:8080/tmaj/client".  You must change this ipaddress and port to the public ip address of your server.  If you do not do this you will not be able to access the tmaj server from another machine.  For example, you might change this to: "http://bui2.win.ad.jhu.edu:8080/tmaj/client" 

Step 7: Deploy Application

  1. Open a dos prompt, and then go to the directory where you unzipped the tmaj zip file.  There will be a build.xml file in it.
  2. ant clean (optional) In case you have run the 'ant push' command before, this will clear the cache and force a full re-build.
  3. ant push   (run this command.  It will deploy the TMAJ application to Tomcat.) Note there is a current bug where sometimes this command has to be repeated because Tomcat does not load in time. The error is a reload error. If you run this command twice, it should work. Note also that you will get a reload error if you use Tomcat 6 or below. Change the URL in compile.properties to fix this, or even better, upgrade to Tomcat 7.0
  4. ant gui  (run this command.  It will bring up the TMAJ gui.)
  5. Initialize Database.  Go to the TMAJ Gui, click the Options Button, then click the Initialize Database button. This will create a default username and password to get into TMAJ.  This username and a hash of the password will go into the Users table in the database.
  6. Verify Login.   Login to TMAJ by clicking the Login Button.  This is the default username and password that was created:
    username: admin
    password: admin

Step 8: Verify Application Works

  1. Verify TMAJ can be accessed from the web.  You're TMAJ webpage may be accessed online at:
    http://127.0.0.1:8080/tmaj/client/       (127.0.0.1 can be replaced with whatever your tmaj server's IP address is.)
    This is the same effect as using the "ant gui" command.
  2. Verify you can import sample images to TMAJ.  Sample scanned images are included in the tmaj zip file you downloaded.  You will find sample images to import here:
    sites\Default\miscellaneous\sample_images\standard.
    Follow the instructions to upload sample images.  You can skip the first few instructions where you are asked to scan the array-slide and put numbers in the image's filename.  This has already been done.
  3. Following the instructions in the link above, make sure you can actually view the images.
  4. Finally, try scanning some images with your own system and see if you can import them into TMAJ.


End Of Installation

Congratulations!  You are finished installing TMAJ. 

Problems or Additional Questions

Please feel free to contact us about any questions on comments you may have.   Some of the questions you have may have already been answered on our FAQs page.  Also, may sure the check both the client and server log for important error messages.  (See section of Log Files below.)


Also, we would like to know if you are using TMAJ so we could get an estimate on how many users it has.  Thank you for your interest!

Technical questions about TMAJ or this process may be directed here:


Log Files

You may check the TMAJ server log for useful error messages.  Remember there is a log for both the TMAJ server and the TMAJ client.  Both filenames are called "tmaj.log".  The tmaj server log will be on the server in the Apache Tomcat logs directory, which should be here:
C:\Program Files\Apache Software Foundation\Tomcat 7.0\logs\tmaj.log

The TMAJ client log will be on the client machine.  It location will depend on where you are executing the Java Virtual Machine (JVM).  If you're running TMAJ from the command line with "ant", then the tmaj client log will simply be in the subdirectory:
logs/tmaj.log

If you executing TMAJ using Java WebStart, you may find the tmaj client log in a variety of places.  For example, when using Mozilla Firefox, the client log is here:
C:\Program Files\Mozilla Firefox\logs\tmaj.log


<< Back to the Manual

© Copyright 2011 | All Rights Reserved | The Johns Hopkins University