These instructions describe the default installation of an OMII server which is not secured by SSL (https). It is recommended that if you are using your OMII server to process jobs containing "real" data, you secure your server by following the instructions in How to setup a secure OMII Server using SSL.
You can install some or all of the OMII Server via the Stack Installer. When installing only the WS container via the Stack Installer, you need to select the following options from the Stack Installer menu one after the other:
Option 1 - Web Services container - database
Option 2 - Web Services container - components
Installation can be performed as the root user or as a non-root user.
1. Download the OMII Server release (typically called omii-server-x.x.x.tar) from http://www.omii.ac.uk.
2. Open a new terminal window and change directory to the location of your downloaded Server release.
3. Log in as the root user using "su -" or as yourself (a non-root user).
4. Unpack your release and then type
$ ./OMIIstackInstall.pl
5. You will see the following:
Welcome to the OMII_X.X.X Server stack installer.
For support issues or queries, please either:
- Visit http://www.omii.ac.uk/support
- Email support@omii.ac.uk
- See the Support section of the OMII Installation & Setup Guide
This installer is designed to take you through the Server installation.
An OMII Server installation consists of a Web Services (WS) container
installation, with optional Software Component components and an optional
Integrated services package.
Please choose the WS container database option (1), followed by the
corresponding component option (2). Then optionally install the Software
Components (3 & 4) and/or the Integrated services package (5 & 6).
Web Services container (See "Web Services container" section in User Guide)
1) Database
2) Components
Software Component (See "Software Components" section in User Guide)
3) Database
4) Components
Integrated Services package (See "Integrated Services" section in User Guide)
Please note that these services depend upon the Account Service which can be
installed via option 4.
5) Database
6) Components
7) Uninstall Options (See "Stack Installer > Uninstallation" in Install Guide)
6. Select option 1 to install the database for the WS container. Database installation is explained in detail in Using the Stack Installer. When complete you will see the message Web Services Database setup complete..
7. Use the Up Arrow to retrieve the previous command from your command history and press Enter.
$ ./OMIIstackInstall.pl
8. Select option 2 to install the WS container components.
9. You are then prompted:
Enter fully qualified hostname (default: omiitest.omii.ac.uk):
Please enter the fully qualified name of the machine hosting your database.
Or just press return for a locally hosted database.
10. You must then enter your database port:
Please enter the port on which your database is running.
Or just press return if it is running on the default port (5432).
If you wish to use a database installed on another machine, enter the IP address of that machine here. If the connection test fails, ensure that the PostgreSQL pg_hba.conf file on the database host machine contains an entry for the machine which is trying to connect to it.
11. Specify OMII_HOME directory (default /usr/local/OMII) :
Press Enter to accept the default location or enter a directory location of your choice. NB. spaces, slashes, and relative paths are permitted but tilde symbols (~) are not. This directory could be in your own user space eg. /home/john_smith.
12. The amount of disk space in your chosen location and your Java version will be verified. Your chosen port will be verified to check that it is free.
13. If the first part of the WS container installation is successful, you should see the following message:
OMII base installation and setup complete.
The base is configured to use the following ports:
- HTTP connector: 18080 (or the port of your choice)
- AJP connector: 18009
- Shutdown Port: 18005
14. The installer continues by testing the WS container installation. If the WS container is running successfully, you should get the following message:
Testing complete. Base setup and run successfully!
The tomcat server installation files are now owned by the user 'omii_tomcat_owner'.
The user 'omii_tomcat_user' has been created and added to the group 'omii_tomcat'.
Any users belonging to 'omii_tomcat' group can start and stop tomcat.
15. Enter the username of any local user(s) you wish to add to the 'omii_tomcat' group and then press Enter.
16. You should see a message stating "Base installation complete".
17. You are now prompted to enter your details so that the OMII can provide you with a temporary keystore and certificate. The OMII generates a unique certificate for you based on your details which is then sent back to your machine automatically after it has been signed by the temporary CA here at OMII. The OMII recognises that this is an insecure unsupported certification authority created for the purposes of testing the secure elements of the OMII software. For operational deployment, please see the section Working with non-OMII Certificates which provides instructions on how to use your own existing certificates from eg. the UK e-science centre.
The temporary certificate expires after thirty days. If you need another thirty days or you have trouble obtaining the keystore during the WS container installation due to the presence of a proxy, please visit http://security.omii.ac.uk/keygen/ in a web browser to receive another one or set the proxy as an environment variable as explained here. The resulting archive file generated by the form must be expanded in the download directory from where the install script runs (eg. omii-server-x.x.x/extension). These files will then be picked up by the installer and used in preference to contacting the OMII certificate server directly. If a proxy is set then the selftest for the tomcat install may also fail.
Please enter your details:
Fully Qualified Machine Name (default: examplemachine.omii.ac.uk) : If your machine name has been correctly detected, press Enter, otherwise, please enter your FULLY qualified machine name.
Organisation (default : eg. ECS) : Please enter the name of your organisation. If you have performed an installation before, your previous details will be retained as the suggested default.
Organisational Unit (default : eg. OMII) : Please enter the name of your organisational unit.
Location (default : eg. Southampton) : Please enter your location.
State (default : eg. Hants) : Please enter your county or state.
Country (default : eg. UK) : Please enter the country the server machine is located in.
Email Address (default : user@somewhere.omii.ac.uk) : Please enter your email address.
Please press Enter in response to the following series of questions which relate to the default location of your OMII keystore.
Please enter the location of the keystore, default is '/usr/local/OMII/omii.ks'. (enter)
Please enter the location of the CRLs directory, default is '/usr/local/OMII/grid/CRLs'. (enter)
Please enter the password of this keystore, default is 'tmpstore'. (enter)
Please enter the alias for the private key contained within this keystore, default is 'omii_server'. (enter)
Please enter the password for this private key, default is 'tmpkey'. (enter)
If you enter a different keystore password from the default during installation and you want to use the keystore provided by OMII, you must also change the password for the underlying keystore. This can be achieved by:
keytool -storepasswd -new NEWPASSWD -storepass tmpstore -keystore omii.ks
18. You will then see a summary,
Summary:
[echo] --------
[echo]
[echo] The keystore to be used is /usr/local/OMII/omii.ks
[echo]
[echo] Java Home is //home/yourdir/java/j2sdk1.4.2_04
[echo]
19. You will see another message stating that installation and test service deployment are now complete.
20. The axisTestService will now be tested. This test service has no security and performs a simple request using a string as a payload. If you see:
[java] Value is 'Received the message 'test_result'. Well Done!'
then the test has been successful. Tomcat is shut down and the installation has finished when you see the message "OMII_x.x.x setup complete".
21. Change directory to the location of your installed OMII server and go to the /bin subdirectory (thereafter known as OMII_HOME/bin) and type:
$ ./startomii.sh
to start your OMII Server.
You can then use a web browser, go to: http://localhost:18080/axis and select the 'List - View the list of deployed Web services' link to check that you can see the newly deployed axisTestService.
The PostgreSQL database is left running at the end of the installation.
This can be done by setting some environment variables. With OMII_PROMPT set to 'off', the OMII Stack installer will ask the user for less input during the installs. With OMII_AUTO set to 'on', defaults will be assumed for all user inputs.
Please see Changing username and password for the "tomcat" role.
