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
- Download the latest version of TMAJ.
You will find the latest version on sourceforge.net. The URL is:
- 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
Step 2: Install Java 6 JDK
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
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
- Ubuntu: If you're using Ubuntu Linux, you can simply run this
to download and install java.
sudo apt-get install
sun-java6-bin sun-java6-jre sun-java6-jdk
- 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
- 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
Step 3: Install Apache Tomcat
- 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:
- 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
- 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.
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
- sudo mv
- nano ~/.bashrc
Add the following line:
- 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
- You may want to verify that Tomcat can be accessed from a
machine, since any tmaj clients will be connecting to TMAJ from other
- To test this, just replace the 127.0.0.1 with your server
address or hostname. So for example, use the URL:
- If the Tomcat installation was a success, you should get to a
"If you're seeing this page via a web browser, it means you've setup
- If for some reason you cannot access the page, make sure you
have the service started.
Step 4: Install Ant
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
- To install Ant on Windows, simply unzip the file you downloaded
into C:\Program Files
Your directory structure will look something like:
- 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
The bin directory would be:
(Make sure that this directory actually exisits. You may have
installed ant somewhere else.)
- Add the java\bin directory to
the path variable. The JAVA_HOME\bin
directory will look something like:
(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:
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
- Add JAVA_HOME environment
variable. Set the JAVA_HOME environment variable to the
location of the Java Development Kit. It should be somewhere
- Add the ANT_HOME environment
variable. Set the ANT_HOME environment variable to the
location where you installed ant. It should be somewhere like:
- Make sure that the JAVA_HOME environment variable has been
set. For example, you can add it to the end of your ~/.bashrc
- sudo apt-get install ant
- Verify Ant Installation
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.
You should get a Build
- 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
- 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
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
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
- Oracle: (tested on Oracle 8i and Oracle
- Sybase SQL Anywhere (tested on SQL Anywhere 8 and 9)
- Get the Install File(s) for the
- 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
installation (For windows this would be "Windows Essentials".)
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.
- 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
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.)
- 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
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
- Go to the database's
client. This is where you will create the database.
It may be a GUI or a text-interface.
start button >> All Programs >> MySQL >> MySQL Server
5.1 >> MySQL Command Line Client >> enter password: db555
sudo mysql --user=root --password=db555
- Create a new database
Name the database: tmaj (this is merely the
default in the config file. You can name the database another
create database tmaj;
- 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
- Go into the new database.
If you're using MySQL, the command is:
- Create the Tables in the
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
If you're using MySQL, the command to use (while in MySQL Command Line
- Microsoft SQL Server: schema_sql_server.sql
- MySQL: schema_mysql.sql
- Oracle: schema_oracle.sql
- Sybase SQL Anywhere: schema_sybase.sql
- 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
slash at the end.) Always
use forward slashes (/) , even in
. You can skip all the verification steps.
there in case you run into problems and you want to retrace your steps.
- Locate the config directory.
You will find it as a top-level directory whereever you unzipped the
- Get the IP Address or Hostname
of your TMAJ Server.
This may be done by opening a dos prompt and typing in
- 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:
- Change the Site variable to whatever the name of your site
is. For example, your site might be "Cleveland Clinic"
- 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
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
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
- database.properties: Set
the values in database.properties to the appropriate values.
- 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.
- db_type: In addition,
you must set the database type to the appropriate type (For example, Oracle or MySQL.)
- 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.)
- port: Make sure you know
what port you database is running on. For example, by default, my
sql runs on 3306.
- db_name: This is the name of your database. By default this is
- 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.
- 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.
- 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
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.
- 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
found in the tomcat-users.xml file. You must restart Tomcat after
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
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
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.
Windows: this will be
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:
------------ ROOT/ (Tomcat installs this by default. When you go
to the http://localhost:8080 in a web browser, these are the files that
------------ tmaj/ (this directory is created later after the
"ant push" step. )
------------------ WEB-INF/ (the "ant push" puts server code here)
- tomcat.webAppName: You should not need to change this.
The default is tmaj.
- 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.
- 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
password you gave for the tomcat.manager.username and
tomcat.manager.password actually work.
- Verify #2: Verify that the
tomcat.home_dir contains a subdirectory called webapps, and that
the webapps directory contains a subdirectory called ROOT.
- Verify #3: Verify that the ServletURL for Tomcat and the tomcat
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.
should show up.
- 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:
will need to manually create this directory.
sudo mkdir /var/tmaj_images
- 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
- 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.
- ant clean (optional) In
case you have run the 'ant push' command before, this will clear the
cache and force a full re-build.
- 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
gui (run this command. It will bring up the
- 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.
- Verify Login. Login
to TMAJ by clicking the Login Button.
This is the default username and password that was created:
Step 8: Verify Application Works
- 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
This is the same effect as using the "ant gui" command.
- 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
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.
- Following the instructions in the link above, make sure you can
actually view the images.
- 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
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:
You may check the TMAJ server log for useful error messages.
Remember there is a log for both the TMAJ server and the TMAJ
Both filenames are called "tmaj.log". The tmaj server log will be
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
depend on where you are executing the Java Virtual Machine (JVM).
you're running TMAJ from the command line with "ant", then the tmaj
client log will simply be in the subdirectory:
If you executing TMAJ using Java WebStart, you may find the tmaj client
log in a variety of places. For example, when using Mozilla
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