Ittrium software is now available in a limited open source software release for use use by web development partners.  The software is provided through anonymous access to our SVN repository and includes an 8 hour license which means the software must be restarted after running for 8 hours. 

The actual java source code is not included in this release, but everything else you need to run Ittrium on any computer is provided here.

Since Ittrium is written entirely in java, the software will run on any operating system that supports java.  The documentation and tools provided have been tested on Windows and Unix based systems including Linux and Mac OS X.

Prerequisite Software

Before you begin, you will need to install the following software.

  1. Java 1.7 or 7 (latest update)  You can download the latest release from Oracle at the following URL.  Ittrium software has been tested with version 1.6 and 1.7.  We typically install the full JDK by default, but the JRE or Server JRE should work as well.

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

  2. MySQL 5.x (latest GA release)  Download MySQL Community Server at the following URL.  New releases of MySQL may also be used, but you may experience problems depending on changes in MySQL.

    http://dev.mysql.com/downloads/mysql/

    Note: When you install MySQL make sure to install both MySQL Community Server and the MySQL Startup Item if you want MySQL to automatically start as a service.

Development Environment (optional)

We recommend using Eclipse as your development environment, but you are free to use any development tools.  Whichever tools you choose, you'll want a quality code editor that provides syntax checking for the following file types.

CSS, HTML, JSP, XML, XSL

Note: Ittrium themes include files with an extension of VAR for variable.  These files are XML files so you'll want to adjust your development configuration to treat these files as XML.

  1. Eclipse 4.2+ (or latest release).  Download the latest stable Eclipse IDE for Java EE Developers

    http://www.eclipse.org/downloads/

  2. Subclipse 1.6 (optional).  Subclipse can be installed from within your Eclipse development environment. 

Setup a Working Directory

Before you begin, you will need to create a working directory where the software components will be installed.  By default, Ittrium uses the following working directory for all of our software instances, but you can use any working directory.

Windows

\var\ittrium

Unix

/var/ittrium

The working directory you choose is up to you, but we'll reference it throughout this documentation using the following variable.

$WORK_DIR$

Environment Variables

Open Ittrium includes various scripts that are used to update and run the Ittrium software.  These scripts depend on two environment variables which must be configured on the computer where you're using this software.  

  1. JAVA_HOME - The location of the Java software you have installed.  
  2. ITTRIUM_HOME - The location of the Ittrium "webserver" directory.  This directory will be created automatically when you run the setup script that follows in these instructions.

Windows

JAVA_HOME

Add a system environment variable that includes something like the following path.  Make sure to replace the path with the actual path to your Java installation.  The directory you specify should contain a sub directory named bin that contains java.exe.

C:\PROGRA~1\Java\jdk1.7.0_45

Note that we're using the FAT file name for "Program Files" to eliminate issues that can arise due to the space in the file name.  You should verify the the directory name by running the following command.

DIR /X

The /X parameter results adds the FAT file name to your directory listing.  On most Windows systems, you'll find that the FAT file name for the 64 bit directory named "Program Files" is PROGRA~1 and PROGRA~2 for the 32 bit directory named "Program Files (x86)"

ITTRIUM_HOME

Add a system environment variable that includes a path to the web server directory that is created when after you execute the setup.bat or setup.sh file later in the installation process.

By default, Ittrium sets ITTRIUM_HOME to the following directory.  This might be different on your system.

$WORK_DIR$/webserver

Unix

Edit or create .bash_profile in your home directory.  Add export statements for JAVA_HOME and ITTRIUM_HOME.  A sample configuration for .bash_profile is listed below.

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_21.jdk/Contents/Home
export ITTRIUM_HOME=/var/ittrium/webserver

SVN Configuration

You will need a SVN client to gain access to the Open Ittrium software.  Any SVN client will do.  If you are a developer who is running Eclipse, you can also install Subclipse which provides the necessary SVN support.  Otherwise we recommend the following open source tools depending on your platform.

Windows

TortoiseSVN 1.8.4 or latest stable release. Download from the following URL and then install the software.

By default TortoiseSVN always has a GUI (Graphical User Interface) associated with it. But on the installer (of version 1.7 and later) you can select the "command line client tools" option so you can call svn commands (like svn commit and svn update) from the command line.  You will need the command line version to complete the instructions that follow.

http://tortoisesvn.net/

Unix

There are any number of SVN clients that you can choose.  Cornerstone is the favorite recommendation of beanstalk (our svn provider).  The provide a complete list to choose from at the following URL.

http://guides.beanstalkapp.com/version-control/clients.html#subversion-clients

Connect to SVN Repository

You can connect to the SVN repository through Eclipse provided that Subclipse has been installed or through the Command line if you have installed an SVN client such as TortoiseSVN.  Instructions for both methods are listed below.

Instructions for connecting through Eclipse

From Project Explorer:

  1. Right click and then select New > Project
  2. From the New Project dialog select General > Project.  Name your new project "openittrium" and then click Finish.
  3. Right click on your new "openittrium" project and select Team > Share Project
  4. Select SVN for your repository.
  5. Select "create new svn repository"
  6. Enter the following repository URL

    https://openittrium.svn.beanstalkapp.com/distribution
  7. Click Finish
  8. The system will prompt you with a warning that the specified folder name already exists in the repository and that you are about check out the folder and overwrite your local copy.  CLICK YES.

Instructions for connecting through Command Line

Windows

1. Open a Command Prompt
2. Change the directory to $WORK_DIR$
3. Enter the following command.  This will download the openittrium software to your working directory.

svn checkout https://openittrium.svn.beanstalkapp.com/distribution/openittrium --username anonymous --password anonymous

Unix

1. Open a Terminal (xterm)
2. Change the directory to $WORK_DIR$
3. Enter the following command.  This will download the openittrium software to your working directory.

svn checkout https://openittrium.svn.beanstalkapp.com/distribution/openittrium --username anonymous --password anonymous

Install Apache Tomcat

Apache Tomcat provides the Java Servlet and Java Server Pages technology that is required by Ittrium.  Version 5.5.36 is provided with the Open Ittrium platform and can be installed by performing the following steps.

Windows

  1. Open a Command Prompt
  2. Change the directory to $WORK_DIR$\openittrium\bin
  3. Run the following command.

    setup.bat

Unix

  1. Open a Terminal session
  2. Change the directory to $WORK_DIR$/openittrium/bin
  3. Run the following command.

    ./setup.sh

When completed, you will see a new directory named "webserver" that is a sibling directory to the directory named "openittrium".  This directory contains the Apache Tomcat software (apache-tomcat-5.5.36) which is referred to in the Apache Tomcat documentation as Catalina Home plus the Catalina Base directory (a00).  This second directory is where the Ittrium software will be installed.

Note: You can run multiple instances of Ittrium on a single server and can also create multiple websites within a single Ittrium instance.  Our recommendation is to run with a single Ittrium instance named a00, but you can also created additional instanced by executing the synch-base script that is documented below. 

If you choose to run multiple Ittrium instances we recommend naming them a00, a01, a02, etc...  You will also need adequate memory.  We recommend a minimum of 256MB for each development instance of the software that you run.

64 Bit Java/Tomcat

Tomcat is preconfigured for 32 bit systems.  If you're running a 64 bit version of Java you will need to perform the following steps.

Windows

Replaced the following two files with the corresponding version that you'll find in one of two 64 bit directories.

tomcat5.exe
tcnative-1.dll

These two files are located in $WORK_DIR$\webserver\apache-tomcat-5.5.36\bin with the 64 bit versions in one of the following two sub directories. 

i64
x64

Chances are you'll need the x64 version of these files.  The i64 versions is for computers running an Intel Itanium series processor that never took off due to poor performance for 32 bit applications.

To upgrade Tomcat, you need to simply replace the standard files (tomcat5.exe and tcnative-1.dll) with the corresponding versions in the x64 or i64 directory.

Unix

There is nothing do here if you are running on a Unix Like system such as Linux or Mac OS/X.

Install/Upgrade Ittrium

Install the latest stable version of the Ittrium software.

Windows

  1. cd $WORK_DIR$\openittrium\bin
  2. svnupdate
  3. synch-ittrium.bat a00

Unix

  1. cd $WORK_DIR$/openittrium/bin
  2. ./svnupdate.sh
  3. ./synch-ittrium.sh a00

Note: If you are running multiple Ittrium software instances, be sure to change a00 to the instance number you ar e upgrading.

You will use this same process anytime you need to upgrade the software.  You use svnupdate to retrieve the latest software from the svn repository and then synch-ittrium to apply those updates to one of your Ittrium software instances.

Create Symbolic Images Directory

All images that are stored in Ittrium are referenced through a symbolic directory named images by default.  Create this directory using the following command

Windows

  1. cd $WORK_DIR$\webserver\a00\webapps\ittrium
  2. Execute the following command

    mklink /d images WEB-INF\blobs

Note: You will need to run this command as an administrator on windows using.

Unix

  1. cd $WORK_DIR$/webserver/a00/webapps/ittrium
  2. Execute the following command

    sudo ln -s WEB-INF/blobs images

Add webserver project to eclipse (optional)

Add a new project to Eclipse named "webserver".

  1. Right Click in Project Explorer ...
  2. New > Project > General > Project
  3. Project Name: webserver
  4. Click Finish

This folder has already been created in step 1.  You'll need this project if you plan to build sites through Eclipse.

Create Ittrium Database

In this step, you will create the Ittrium database that will be used with your new software instance.  To create the database, open a MySQL command prompt and then execute the following SQL statements.

  1. create user 'agusers'@'localhost'; 
    Note: Ittrium is configured to connect using a user id of 'agusers' by default.  You can add a password or change the user id if needed, but you will need to override the user id and/or password in through bootstrap.xml.  You can find additional details regarding new MySQL user creation here.
  2. create database a00ittrium;
  3. use a00ittrium;
  4. source $WORK_DIR/openittrium/tools/server/sql/mysql/boot1-83-mysql.sql;
  5. source $WORK_DIR/tools/server/sql/boot2-82.sql;
  6. grant all privileges on a00ittrium.* to agusers@localhost;
  7. grant grant option on a00ittrium.* to agusers@localhost;
  8. grant file on *.* to agusers@localhost;

Note: Pay special attention to the step, Configure Ittrium Database,  since you will need to configure the Ittrium software to use the database you just created.

Create Ittrium Logging Database

In this step, you will create the Ittrium logging database.  This database is used to capture logging details and also includes key tables that are used during the upgrade process when upgrading freeform application components (gizmos) to the most recent release.

  1. create database ittriumlogging;
  2. use ittriumlogging;
  3. source $WORK_DIR/openittrium/tools/server/sql/mysql/logging-dbms-mysql.sql;
  4. source $WORK_DIR/openittrium/tools/server/sql/mysql/logging-gizmos-mysql.sql;
  5. source $WORK_DIR/openittrium/tools/server/sql/mysql/logging-ecommerce-dbms-mysql.sql;
  6. grant all privileges on ittriumlogging.* to agusers@localhost;
  7. grant grant option on ittriumlogging.* to agusers@localhost;

 

Create Ittrium Dashboards Database

In this step, you will create the Ittrium Dashboards database.  This database is initially empty, but is used as a default location for database tables that may be required by your freeform applications.  We intentionally separate these database tables from the tables that are used by the content management software.

  1. create database a00ittrium_dashboards;
  2. use a00ittrium_dashboards;
  3. grant all privileges on a00ittrium_dashboards.* to agusers@localhost;
  4. grant grant option on a00ittrium_dashboards.* to agusers@localhost;

NOTE: When connection to this this database from a freeform application, you will referenced a named database connection.  The default connection name is "DASHBOARDS".

Configure Ittrium Database

In this step, you need to changed the Ittrium configuration to use the database you created in the previous step.  To do this, you'll need to edit the file named.

$WORK_DIR$/webserver/a00/webapps/ittrium/WEB-INF/conf/bootstrap.xml

Locate and change the following and change the following statement that you'll find in the <setDefaultFactory> section of this XML document.

From

<setConnectionURL class="xsd:string">jdbc:mysql://localhost/ittrium</setConnectionURL>

To

<setConnectionURL class="xsd:string">jdbc:mysql://localhost/a00ittrium</setConnectionURL>

Note: If you are running multiple Ittrium software instances, you will need to create a separate database for each instance and then make the corresponding change to bootstrap.xml.

Install Tomcat/Ittrium Service

You now need to create the service that you'll use to start and stop the Ittrium software

Before installing the service, you'll need to verify that the environment variables for JAVA_HOME and ITTRIUM_HOME have both been defined.

Windows

  1. cd $WORK_DIR$\webserver\apache-tomcat-5.5.36\bin
  2. execute the following command where a00 is the Ittrium software instance for which you are installing the service

    ittrium-service install a00

Note: You will need to run this command as an administrator using "Run As Administor" on your Windows system.

Unix

For Unix platforms, we currently use JSVC to configure and start the Ittrium service and are currently looking into the Apache Portable Runtime project.  Documentation for building and configuring jsvc can be found on the Apache website at the following address.

http://commons.apache.org/proper/commons-daemon/jsvc.html

The instructions for building and running JSVC vary depending on your operating system.  Ittrium has pre-configured service scripts for the following platforms.

  • CentOS 6.2

If you're a developer, we recommend starting your service through Eclipse (see instructions below).

Eclipse

Open Ittrium comes pre-configured with several launch configurations, one of which can be used to start the the default service named a00 from within the Eclipse development environment.  From within your Eclipse environment, you'll find the launch configuration for starting Ittrium at the following location.

$WORK_DIR$\openittrium\software\eclipse\launch-configurations\service-a00.launch

When you're ready to start the service, you can perform the following steps.

  1. right click service-a00.launch
  2. select Run As
  3. select service-a00

This will start the ittrium service named a00 and will automatically add service-a00 to your Run Configuration menu.  You can then start the service from the Run menu.

Server Ports

There are three TCP/IP ports that are used for each Apache Tomcat Catalina Base instance that are all preconfigured for the a00 instance.  If you're deploying additional instances you need to update these ports for your instance.

Perform the following steps to update the ports.

  1. cd $WORK_DIR$/webserver/ann/conf
  2. Edit server.xml
  3. Change the Server port for 8005 to 8nn5
  4. Change the Server name from a00 to ann
  5. Change the AJP1.3 Connector port from 8009 to 8nn9
  6. Change the HTTP Connector port from 8000 to 8nn0

    NOTE: The HTTP Connector port is optional and can be commented out if you are running behind Apache Web Server or IIS.

  7. Save your changes

Start the Ittrium Service

You're now ready to start the Ittrium service.  Once you have started the service, you'll be able to access your site through the following URL.

http://localhost:8000 [where 8000 is the http port configured in the file named server.xml that you recently changed.]

To start the service

Windows

Start the service named Ittrium a00 through Service Manager.

Unix

We currently only have documentation for starting the service on our own CentOS environment using the following command.

service a00 start

If you need to run open ittrium on a Unix Like operation system outside of Eclipse, please contact Ittrium.

Eclipse

Use the pre-configured launch configuration named service-a00 to start the service.

Install Preset Scripts

Here you need to install the initial setup scripts.  To do this you need to open the following file in your web browser.

$WORK_DIR$/openittrium/tools/local/BootLoad.html

This HTML file contains a simple form that you can use to execute the setup scripts, check statistics on your software plus several other features that we'll cover later. 

You'll need to install the following scripts to complete the setup process for your new Ittrium instance.  For each script, you will need to set the following 4 parameters through this form.

URL: http://localhost:8000/ittrium
User ID: admin
User Password: admin
Action: Execute Script

You'll find the four scripts you need to load through the File parameter in the following directory.

$WORK_DIR$/openittrium/tools/local/anttasks/setup

Select each of the following four files one at a time and then press the Do button to load and execute the script.

  1. ant-preset1-permissions.xml
  2. ant-preset2-pilotvisible.xml
  3. ant-preset3-contenttypes.xml
  4. ant-preset4-tools.xml

When each script executes, the system will return an XML document showing the status of the script.  Verify that there are no errors.

Web Server Configuration

The next step will vary depending on how you plan to service incoming HTTP requests.  If you are going to run behind a web server such as Apache Web Server or IIS, then you should proceed to the corresponding documentation for the web server you plan to use.

If you are servicing HTTP requests through Apache Tomcat, then you need to make a simple configuration change so that requests for css and javascript files are resolved problem.  To make this change you will need to edit the following file.

$WORK_DIR$/webserver/a00/webapps/ittrium/WEB-INF/web.xml

You'll need to remove the comment on the following configuration section.  Change the configuration

From

        <servlet-name>staticfile</servlet-name>
        <servlet-class>com.ittrium.core.servlet.AgStaticServlet</servlet-class>
        <!-- For standalone download support without Apache, include the following -->
<!--
        <init-param>
            <param-name>file</param-name>
            <param-value>/site</param-value>
        </init-param>
-->

To

        <servlet-name>staticfile</servlet-name>
        <servlet-class>com.ittrium.core.servlet.AgStaticServlet</servlet-class>
        <!-- For standalone download support without Apache, include the following -->
        <init-param>
            <param-name>file</param-name>
            <param-value>/site</param-value>
        </init-param>

By making this change, Apache Tomcat will service all requests for the /site directory.   It's through this directory that we access the public LAF files that include your public CSS for your site as well as the system CSS and JS files for all of the administration tools.

You'll need to stop and then restart the Ittrium a00 service after making this change.

NOTE: Be sure to remove write permission to this file after making this change.  Otherwise, your changes will automatically be updated the next time you update your software.

known issues

Eclipse

Problem: If you install Eclipse under your user directory on mac os/x, you may experience a problem indicating "Permission Denied" the first time you try to access a web page.  By default, Ittrium is configured to write certain output files through MySQL to a well known Ittrium directory.  Since this directory is within your user directory, MySQL will not have access to write to this directory.

Solution: Locate blobs-custom.xml in your webserver/a00/webapps/ittrium/WEB-INF/properties directory and change the location of the temporary directory as follows.

<?xml version="1.0" encoding="UTF-8"?>
<BlobMap>
    <type keytype="-1">
        <name keystring="uploadTempDir">
            <string>/tmp/</string>
        </name>
        <name keystring="uploadMaxSize">
            <value class="xsd:int">5000000</value>
        </name>
        <name keystring="uploadTempBoundary">
            <value class="xsd:int">10000</value>
        </name>
    </type>
</BlobMap>

In this example, we're instructing the system to use the default "tmp" directory as the location for writing temporary files.  MySQL will have access to this directory.