You need to decide in which directory the final server (not the source code you're creating it from) should live and make sure, before running the installation script, that this directory exists and that the non-privileged installation user has write access to it. Following UNIX tradition an obvious directory to create for this is /usr/local/emboss, but you can choose anywhere in your filing system.

There is one caveat; it is recommended that the server be installed to directly attached disc rather than disc attached via (e.g.) NFS. Network-accessed disc can, in some cases, have a very detrimental effect on Tomcat server performance. So:

You also need to decide where the user results will be kept on the server. The server will automatically create subdirectories under this location for each user who runs an EMBOSS application. How much space is required will, of course, depend on how many users you have and how much use they'll make of the server. You will have to devise your own strategy for managing this disc space e.g. whether you leave user results there permanently or delete them after a certain period. The directory must be world writeable and it should have the sticky bit set e.g.:

We recommend installing Jemboss using the installation script supplied as part of the EMBOSS-x.y.z.tar.gz bundle. It lives in the subdirectory jemboss/utils and is called install-jemboss-server.sh.

This script should be run as an unprivileged user. The Tomcat server associated with Jemboss will end up being run under this username.

In most cases the installation script will produce a default response. If this is the value required then you can just press <RETURN>. The examples below always show a fully typed response for clarity.

Here is a typical run for setting up an authenticating server:

--------------------------------------------------------------
         EMBOSS and Jemboss Server installation script
--------------------------------------------------------------
 
Note: any default values are given in square brackets [].
 
This script installs EMBOSS as well as Jemboss.
Jemboss is deployed as a Java web application in your tomcat server.
A script is prepared to run Jemboss client that by default uses the
above Jemboss web application.

For detailed information on installing jemboss see: 
http://emboss.open-bio.org/Jemboss/install/setup.html


*** This script needs to be run with permissions to be able
*** to install EMBOSS in the required directories. This may
*** be best done as root or as a tomcat user.

Before running this script you should download the latest:

(1) EMBOSS release (contains Jemboss) ftp://emboss.open-bio.org/pub/EMBOSS/
(2) Tomcat release http://tomcat.apache.org/
(3) Apache AXIS (SOAP) release 1.4   http://ws.apache.org/axis/

Have the above been downloaded (y/n)? 
y

These packages are part of the prerequisites given above so ought to have been downloaded and installed at this stage, so y has been typed. Typing n would abort the installation.

Select the platform that your Jemboss server will be
run on from 1-8 [1]:
(1)  linux
(2)  aix
(3)  irix
(4)  hp-ux
(5)  solaris
(6)  macosX
(7)  OSF
(8)  FreeBSD
1

This example installation assumes the Linux operating system is being used.

The IP address is needed by Jemboss to access
the Tomcat web server.
Enter IP of server machine [localhost]:
192.168.8.11

Whereas the default value of localhost will work in most cases it is always preferable to use the full IP address of the server; 192.168.8.11 in this example. Using the full IP address always works, as long as it's the right address.

Enter if you want the Jemboss server to use data
encryption (https/SSL) (y,n) [y]?
y

It is difficult to see why you would not want to use data encryption. The overhead in doing so is very slight. You should certainly use data encryption with any authenticating server.

Enter port number [8443]
8443

8443 is the default port through which the two-way communication occurs between the client and the server. You may change this here but you must make sure that whatever port you choose is both free and not disallowed by any firewall you have in operation.

Enter java (1.4 or above) location [/usr]:
/usr/local/java

This is the location of the top-level directory of your SUN or OpenJDK Java JDK installation.

Enter EMBOSS download directory
[/m1/EMBOSS-6.1.0]:
/m1/EMBOSS-6.1.0

This is the top level directory of the EMBOSS source code after extraction from the compressed tar file. The installation script works out the default value as being two directories above the location from where the installation script was invoked. In this example the script was invoked from /m1/EMBOSS-6.1.0/jemboss/utils/ and the suggested value is correct.

Enter where EMBOSS should be installed [/usr/local/emboss]:
/usr/local/emboss

This is where the compiled server will be installed, described under 'Creating installation and results directories'. Following UNIX convention the default location is under /usr/local.

Enter URL for emboss documentation for application 
[http://emboss.open-bio.org/]:
http://emboss.open-bio.org/

Jemboss will look for EMBOSS application documentation over the network. The default URL is the main documentation site. It should only be changed if you wish to use a mirror of the main site.

Do you want Jemboss to use unix authorisation (y/n) [y]?
y

This is an authenticating server installation so the answer is y. If you answer n then anyone will be able to connect to the server; usernames and passwords are not required.

Provide the UID of the account (non-privileged) to run Tomcat,
it has to be greater than 100 [501]:
501

You are, or should be, running this installation script under the username that will be running the Jemboss/Tomcat server. That being the case, the installation script will try to determine the UID associated with the current username and set the default response appropriately. In the above example, the default is correct i.e. the installation script has found the appropriate UID.

Unix Authentication Method, see:
http://emboss.open-bio.org/Jemboss/install/authentication.html

(1) shadow      (3) PAM         (5) HP-UX shadow
(2) no shadow   (4) AIX shadow  (6) Re-entrant shadow
(7) Re-entrant no shadow

Type of unix password method being used 
(select 1, 2, 3, 4, 5, 6 or 7 )[3]
3

This is, perhaps, the most technical question in the installation. See later for a more complete description. Suffice it to say for now that the installation script will usually set the correct default. It does this based on what you typed in response to the operating system question earlier. As a heuristic, if your operating system has PAM then choose it.

Define the directory you want to store the results in
[/tmp/SOAP/emboss]
/fu/bar/results

This is the results directory described under 'Creating installation and results directories'. You almost certainly do not want to accept the default location as the /tmp filesystem is usually limited and is often wiped clean after a system reboot.

Enter Tomcat root directory (e.g. /usr/local/tomcat)
/fu/bar/apache-tomcat-5.5.27

This is the location of Tomcat as described under 'Installing Tomcat and Axis'

Enter Apache AXIS (SOAP) root directory (e.g. /usr/local/axis)
/fu/bar/axis-1_4

This is the location of Axis as described under 'Installing Tomcat and Axis'

--------------------------------------------------------------

The libraries for EMBOSS (libpng and gd) appear to be in /usr,
if these are the correct libraries then there should be no need
to add any configuration options.

Enter any other EMBOSS configuration options (e.g. --with-pngdriver=pathname)
or press return to leave blank:

At this point the installation script has tested to see whether it can find the png / gd / zlib headers on your system. PNG graphics are required for Jemboss to display and store any graphical output from EMBOSS. The script will look for the headers under /usr, /usr/local, /opt/freeware and /usr/freeware. If, however, the script cannot find your PNG installation then you should enter it here.

This prompt is also an opportunity to add any special compiler or linker flags peculiar to your operating system. On many operating systems you will not need to do this. This is the case in this example so <RETURN> was pressed.

At this point the script will configure, compile and install EMBOSS and Jemboss. You will see hundreds of lines scrolling up your terminal screen as this happens. Depending on the speed of your machine this may take 5-60 minutes. Eventually you will receive the following prompt.

--------------------------------------------------------------

EMBASSY packages can optionally be installed along with
the EMBOSS applications, see:
http://emboss.open-bio.org/rel/dev/apps/
where 'release' corresponds to the EMBOSS version e.g. "R3", "R4", "R5" etc.

--------------------------------------------------------------

Install EMBASSY packages (y,n) [y]?
n

The 'Installation of EMBASSY packages' subsection above described the pre-installation steps you need to do if you wish to install EMBASSY applications under Jemboss. If you require EMBASSY package installation then type 'y' at this prompt. You will then be given the option to install all such prepared packages or to choose them individually; the latter option is useful for developers as it allows non-EMBASSY directories to be skipped (e.g. CVS directories).

This simple installation example chooses not to install any EMBASSY packages.

After the selection of any EMBASSY packages the installation script will then configure, compile and install them either en masse or individually. You will then return to the general installation script prompts.

-------------------------- ClustalW --------------------------

To use emma (EMBOSS interface to ClustalW) Jemboss needs to
know the path to the clustalw binary.

Enter the path to clustalw or press return to set
this later in jemboss.properties

/usr/local/bin

The clustalw binary is required by the EMBOSS application emma. You can either enter the location as above or add it to the jemboss.properties file at a later stage. The latter file is described elsewhere in this chapter.

-------------------------- Primer3  --------------------------

To use eprimer3 (EMBOSS interface primer3 from the Whitehead
Institute) Jemboss needs to know the path to the primer3_core
binary.

Enter the path to primer3_core or press return to set
this later in jemboss.properties
/usr/local/bin

The primer3_core binary is required by the EMBOSS application eprimer3. You can either enter the location as above or add it to the jemboss.properties file at a later stage. The latter file is described elsewhere in this chapter.

After this prompt the installation scripts will create wossname.jar, jemboss.properties and manifest files. Many lines will scroll up your terminal screen.

If you have selected https encryption you will now be asked for a password.

--------------------------------------------------------------

Client and server certificates need to be generated for the
secure (https) connection. These are then imported into
keystores. The keystores act as databases for the
certificates.

For details see:
http://emboss.open-bio.org/Jemboss/install/ssl.html

--------------------------------------------------------------

Provide a password (must be at least 6 characters):
helloworld

This password will end up in the server.xml file of the Tomcat server and, whereas it will not be visible to non-privileged users, it will be visible to other system administrators on your server.

Provide the validity period for these certificates, i.e. the
number of days before they expire and new ones need to be made [90]:
90

This question is self-explanatory. Elsewhere in this chapter it is described how to create new certificates once the initial ones expire.

At this point the certificates will be created and more lines will scroll up your terminal screen.

Tomcat XML deployment descriptors have been created for the Jemboss Server.
Would you like an automatic deployment of these to be tried (y/n) [y]?
y

This is a sensitive point in the installation. You should certainly try to deploy the XML at this stage, hence the prompt has been answered with y. The installation script will now print some XML to the screen at this point. You should follow the instructions on screen to copy it into your Tomcat configuration directory. There is usually a rather obvious place to paste the XML, namely before the line which says:

Define a SSL HTTP/1.1 Connector on port 8443

You will see that the definition of that connector has been commented out so there is no danger of the definitions clashing.

Be aware that the server.xml file mentioned below also defines an HTTP connector on port 8080. If that number is already in use on your system then you should change it.

1) COPY & PASTE THE FOLLOWING INTO 
   /fu/bar/apache-tomcat-5.5.27/conf/server.xml

    
    Connector port="8443" minProcessors="5" maxProcessors="75"
               enableLookups="false"
               acceptCount="10" debug="0" scheme="https" secure="true"
               useURIValidationHack="false"
               
keystoreFile="/usr/local/emboss/share/EMBOSS/jemboss/resources/server.keystore" 
keystorePass="helloworld"
               clientAuth="false" sslProtocol="TLS"/>


To continue you must have changed the above file(s)!
Have the above files been edited (y/n)?
y

Before typing y it is as well to check that no Jemboss server is currently running from a previous installation otherwise deployment will fail. Use the UNIX command ps in a separate terminal to check for any likely server processes.

After typing y the following text will appear on screen.

Please wait, starting tomcat.......
Using CATALINA_BASE:   /fu/bar/apache-tomcat-5.5.27
Using CATALINA_HOME:   /fu/bar/apache-tomcat-5.5.27
Using CATALINA_TMPDIR: /fu/bar/apache-tomcat-5.5.27/temp
Using JRE_HOME:       /usr/local/java

At this point the Tomcat server will have been started but there will be a 30 second pause before the deployment is attempted. This gives the server time to finish its initialization. When the deployment happens the following text should appear. The WARNING on the second line should be ignored.

Jan 8, 2007 4:03:40 PM org.apache.axis.utils.JavaUtils isAttachmentSupported
WARNING: Unable to find required classes (javax.activation.DataHandler and 
javax.mail.internet.MimeMultipart). Attachment support is disabled. 
Processing file JembossServer.wsdd
Done processing

--------------------------------------------------------------
--------------------------------------------------------------

Tomcat should be running and the Jemboss web services deployed!
(see https://192.168.8.11:8443/axis/)

It is *very* important to now:
1. As root:
   chown root /usr/local/emboss/bin/jembossctl
   chmod u+s /usr/local/emboss/bin/jembossctl
2. Ensure that tomcat is running as the non-privileged user,
   with the same UID (i.e. 501) that was given to this script
   (and NOT as root!).
3. Use the tomstop & tomstart scripts in this directory
   to stop & start tomcat.

Try running Jemboss with the script:
   /usr/local/emboss/share/EMBOSS/jemboss/runJemboss.sh

To create a web launch page see:
http://emboss.open-bio.org/Jemboss/install/deploy.html

If the deployment fails then it will probably do so with a Java stack trace, in which case look at the troubleshooting section (Section 3.11, “Troubleshooting JEMBOSS Installation”). The server relies on a setuid root program to be able to masquerade as a remote user. These permission changes can only be done by root:

At this point the Tomcat server will be running and can be tested using a script created during the installation. As the unprivileged user try out the Jemboss interface by typing:

Navigate, within the interface, to the embossversion application and click on Go. If all is well then a window will pop up showing the EMBOSS version being used.