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.   The download is free, but you will need to set up a username and password.
  2. Unzip the zip file.  If you don't have a zip file utility, and you're using Windows, you may want to choose WinZip.  Windows XP comes with support for zip files.

Step 2: Install Java

  1. Download the Java 6 JDK.  You must have Java 6 for TMAJ to work.  It is not compatible with Java 1.4 and Java 5. You need to download the JDK (Java Development Kit)  and not the JRE (Java Runtime Environment.) The Java Runtime Environment allows you to run Java application, while the JDK allows users to develop in Java.  You should get the JDK because it includes the JRE and also some additional tools.
  2. Install Java.  If you are on a Windows machine, all you need to do is double click the .exe file you downloaded.
  3. 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 http://www.jgoodies.com/download/jdiskreport/jdiskreport.jnlp.

Step 3: Install Tomcat

  1. Download Apache Tomcat.  You should get the latest version of Tomcat.  The current version of Tomcat is 6.0.  It's okay if you want to use Tomcat 5.0 or Tomcat 5.5.  It's probably okay to use Tomcat 4 but this has not been tested.  You can download the binary copy.  You don't need the source copy.  If you are using Windows, you should download the "Windows Service Installer" -- it's a .exe file that's relatively simple to install.
  2. Install Tomcat.  Follow the instructions on Tomcat's web page to install Tomcat.  If you're using Windows, it is as simple as double-clicking on the .exe file you just downloaded.
    During the Windows install, you will be prompted for a few values:
    [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.
    These are the default values in the TMAJ config file, but you may use different ones.  You should use a different password.
        Port: 8080
        Username: admin
        Password: tomcat555
    Any of these values may be changed later.  You should use a different password.  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.)
  3. Verify Tomcat Installation (Optional).  Point your web-browser (Internet Explorer, Firefox, etc)  to your main Tomcat webpage.
    It 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: 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."

Step 4: Install Ant

  1. Download Apache Ant.  There will be a zip file of ant that you can download that looks something like: apache-ant-1.7.0-bin.zip.  If you are installing an operating system other than Windows, please check the Ant website for the instructinos 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/
    --lib/
  3. Add the bin/ directory to the Path.  Path is a Windows Environment Variable.  Google for Windows Enviroment Variables if you do not know how to set them.  The bin directory would be: C:\Program Files\Ant\bin
  4. 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_01
  5. 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
  6. Verify Ant Installation (Optional). 
    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.

Step 5: Setup the Database

  1. Determine the database you want to use.  We recommend MySQL since it is open source (free) and the easiest to install.  If you are going to have an especially large database, you may want to use Oracle.  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 the installation will be specific to the database you choose.
    Currently, TMAJ supports the following databases:
    • Microsoft SQL Server (tested on SQL Server 2005)
    • MySQL (tested on MySQL 5.0)
    • 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 version 5 or later.  You will only need the minimum installation (For windows this would be "Windows Essentials".)  It is recommended that you later install PhpMyAdmin.  PhpMyAdmin is a web-interface for administration of a MySQL database.
    • Oracle
    • Sybase SQL Anywhere: You may use SQL Anywhere version 8 or later.  The current version is 10.  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.)
    The default values used in the tmaj config file are:
    username: root
    password: db555
    database name: tmaj
  4. 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
  5. 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 teh 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.  These were created when you installed tomcat.  If you need to change these they can be found in the tomcat-users.xml file.  You must restart Tomcat after changing them.
    2. tomcat.home_dir: 
      Windows: this will be something like "C:/Program Files/Apache Software Foundation/Tomcat 6.0". 
      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 6.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. 
    4. tomcat.manager.url: The default is http://127.0.0.1:8080/manager 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.
    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 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 webapps contains a directory 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://bui.win.ad.jhu.edu:8080/RELEASE-NOTES.txt).  Your modification should show up.
  6. server.properties:
    1. Images_Root_Directory: This is the directory where all the image files in TMAJ will go.  The images are not stored into the database.  This directory must be readable and writable by the tomcat service. 
  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.)
  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. 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: Import Images

  1. Make a directory called images.  This should be done in your tmaj web application under tomcat.  For windows, it would look like this:
    C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\tmaj\images
  2. Unzip sample_images.zip into the images directory.  For windows, the directory will look something like this:
    C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\tmaj\images\TMA_0001_CUT_055_SCAN_01_WG1573_8012345_STANDARD_sample.  If you are confused on the location of this directory, see the tomcat directory structure listed in a previous step.
  3. ant gui (Open a command prompt, and run this command in the directory where you unzipped tmaj.)
  4. Log into TMAJ and then click the Import Button.
  5. Click the Add Button then select the directory you just unzipped: TMA_0001_CUT_055_SCAN_01_WG1573_8012345_STANDARD_sample.
  6. Click the Start Button.
  7. Verify Images were Imported (Optional).  Go to the main screen and click the Reset Button.  (This refreshes the cache -- you have just added a new set of images.)
    Next open the images application by clicking the Images Button.  Go under My Projects and highlight the scan.  Then click the new button.  A dialog will pop up to create a new session.  Click the create button. This will create a new session.  Highlight the session and then double-click on it.  If your import when okay, you will be able to see images. 
  8. 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.)


End Of Installation

Congratulations!  You are finished installing TMAJ. 


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, 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:



<< Back to the Manual

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