Toro Installer Documentation

This article describes the Toro Portal Installer workflow and each configuration item.

The installer was implemented using an open source project called AntInstaller, which is a nice application that uses Ant to perform the installation tasks. For further information about AntInstaller, visit their Sourceforge page (http://antinstaller.sourceforge.net/).

One of the functions of this installer is that it does install uPortal itself and performs some minor configurations. It may make changes to such files as portal.properties, security.properties, personDirectory.xml and ldap.xml. These files are first backed up before any changes are made to them. The installer will create a directory called toro_installer_backups where it keeps versions of changed files. It will add '.orig' to any file it first encounters so it's easy to tell what the original file was. Any additional backups are done with a '.n' extension, where n is an numerical index and is incremented on each backup (e.g. personDirectory.xml.4).

Although it's great that these files are backed up, it's a good practice to make a full backup of the Tomcat home directory prior to installing. It's also a good idea to back up the database as well.

Prerequesites

• Tomcat 5.5.x installed on the target machine.
• Java runtime environment 1.5 or higher (for running the installer and the portal/channels)

Running the Installer

To start the installer, double click toro-installer-x.x.x.jar or run it from the command line with: java -jar toro-installer-x.x.x.jar.
Alternatively, you can run the installer in command-line mode by running: java -jar toro-installer-x.x.x.jar text. In command-line mode, you navigate through the same screens as presented below, so this document applies to both modes.

The first screen is the welcome screen.

Click 'Next' to take you to the combined license agreement.

Read and Click 'Accept' to start the configuration.

Here you would specify the maven repositories. The defaults are appropriate for most cases. Click 'Next' to advance to the next page.

You can use this gui (or in command-line mode) to build a specification that you can then execute later. This is useful if you need to remote into the server for the installation and only have access to the command line. It's simpler to configure using the gui vs. command-line. Whenever you run the installer it creates a file called 'ant.install.properties' in the current working directory. By checking this box, it will simply cause the installer to skip the actual installation and leave the ant.install.properties file. To utilize this file, copy it to the target machine and run the installer from the same directory with 'java -jar toro-installer-x.x.x.jar text-auto'. If the hostname is the same as specified (on a later screen), then it will automatically execute. It may complain about trying to run the installer in remote-config mode, to get around this simply edit the ant.install.properties file and set remote-config = false as it instructs.


Click 'Next'.

Specify the path to the TOMCAT_HOME. The installer assumes installation into a Tomcat container.

Click 'Next' to advance to the next page.

If you want to install everything, just select this checkbox. This is a shortcut to having to select all the deployable options.

Click 'Next' to advance to the next page.

Here's another shortcut. Select this checkbox if you want to initialize all the related database tables.

Warning: selecting this may cause all your uPortal and previous Toro installation to be wiped out and re-initialized. On a later screen, you will have the option to 'create tables only'. This will prevent dropping any tables and wiping out any data.
Click 'Next' to proceed.

If you didn't select 'Deploy All', the installer displays this page so you can select what subset of uPortal components you'd like to install.

If initialize all components wasn't specified, this page is presented. Select which uPortal components to initialize and click 'Next' to proceed.

This combined with the deploying all the portlets on the previous screen is equivalent to performing a uPortal initportal.

Select which version of uPortal to install (or that's already deployed if not selecting to install uPortal) and click 'Next' to proceed.

• Multibox - Select this if you are installing into a multibox application server environment. This will configure portal.properties as well as some Toro backend components appropriately.
• uPortal webapp name - The desired webapp name.
• Portal http protocol - Select either http or https. Use of https is highly recommended to avoid session hijacking attacks and opportunities to evesdrop on personal information presented in the portal.
• Server hostname - Select the hostname for the entry point to the portal. If you are putting apache in front, this should be hostname where apache is running.
• Server port - specify which port to use. If using port 80, you will still need to specify it here. And don't forget the leading colon.

Select 'Next' to continue.

If you didn't select 'Deploy All', the installer displays this page so you can select which Toro portlets to deploy and click 'Next' to proceed. Note, selecting an option here will require initialize the appropriate backend system in the 'initialize toro tables' screen.

Select 'Next' to advance.

Again if deploy all components wasn't specified, this page is also presented. Select which Toro channels to deploy and click 'Next' to proceed. Note, selecting an option here will require initialize the appropriate backend system in the 'initialize toro tables' screen.

Select 'Next' to advance.

If you are using a directory server and want to configure it here, select this option. Note, configuration changes to ldap.xml and personDirectory.xml are done by adding what is specified here. So if they have already been configured, you will need to remove them from uPortal. Otherwise, they will get added twice. It is recommend to remove them and let the installer configure perform the configuration.

Select 'Next'.

If 'Configure a Directory Source' was selected on the previous screen, this screen will be displayed. Set the values as appropriate and click 'Next'. Note, the first checkbox should say 'Configure as security context source' and if selected will add to the configuration of security.properties. This is a destructive step and will remove any previous configurations in the security.properties file.

There is a choice here to configure more directory servers. If specified, the workflow goes back to the previous screen to specify the next server. Up to four directory servers can be specified.

Click 'Next' to advance.

If a component was selected that requires an smtp server for sending email, this screen is presented. Add the appropriate values and click 'Next'.

If the web-content-portlet (or the deploy-all option) was selected to be deployed, this screen is displayed.

If RedDot is not being used, this step can be skipped. However, in a non-remote installation the Reddot home directory is required to exist. You will need to either create a dummy directory or specify something that already exists (e.g. /tmp).

Select 'Next'.

Here some miscellaneous filesystem paths are defined.

• Tomcat host path - This is where the web application context files are located. One context xml file will be created for each web app (portlet) that was selected.
• Toro Data Home - A mounted or shared directory to which all application servers have access. Toro channels/portlets store related data here.
• Aspell executable - If aspell is installed on the server, specify its location here.

Select 'Next'.

This screen allows the jdbc settings to be specified. Note that only one source can be specified, but that each component gets their own pool.

Select 'Next'.

If initialize all components was not selected, this screen is presented. Below is the dependency matrix. All components require Toro Common initialization, all portlets require Alchemist and Portlets Common, and all channels require Channels Common.

Select 'Next'.

Selecting this will not cause any tables to be dropped in the initialization phase.

Warning: Unchecking the "Create Tables Only" box instructs the installer to DROP EXISTING CONFLICTING TABLES, if any. This can DESTROY EXISTING DATA if the installer is configured to access a previously provisioned RDBMS. De-activate this checkbox only with care and caution. In the normal course of using the installer, there is no reason to un-check this box.

Select 'Next'.

Confirm the installation.
Select 'Install' to continue.

The installer in action. It is executing a series of ant targets designed to execute the configuration specified.

If all goes well, this finished dialog will popup.