1. | Prerequisites |
1.1. | Java Environment |
1.2. | Database |
1.3. | Application Server |
1.4. | Installation Package |
1.5. | Internet Connection |
1.6. | Pre-Installation |
2. | Installation |
2.1. | IntraLibrary Web Application |
2.2. | Configuring Properties |
2.3. | Deploying the Licence |
2.4. | Configuring the intraLibrary Context |
2.5. | Configuring a Datasource |
2.6. | Copying Dependencies |
3. | Database Setup |
3.1. | Creating the Database |
3.2. | Populating the Database |
3.3. | Database Configuration |
4. | Confirming Installation |
5. | Setting the Application URL |
6. | Backups |
7. | Troubleshooting |
This version of intraLibrary relies on the Java 1.7 Runtime Environment. For this version of intraLibrary to function, it must be running under Java 1.7.
The full jdk must be installed and available on your server. The jre alone is not enough. The Java 1.7 jdk is available for many platforms here: http://www.oracle.com/technetwork/java/javase/downloads/index.html
We currently recommend that it is installed on Ubuntu 10.04 x64 LTS or RedHat Enterprise Linux 6 x64.
Note that intraLibrary has not been tested on the Blackdown port of the JVM, the IBM JVM or any other JVM not mentioned above.
IntraLibrary is designed to run using using the MySQL database server. You will require MySQL version 5.1 for this version of intraLibrary.
MySQL 5.1 is available for many platforms here: http://dev.mysql.com/downloads/mysql/5.1.html/
This release of IntraLibrary it should be deployed to a Apache Tomcat 7 application server.
For help in deploying this you should contact a member of our support team.
It is currently recommended that you run IntraLibrary with the following JAVA_OPTS. The easiest way to achieve this is to create a file called setenv.sh in the Tomcat bin directory:
JAVA_OPTS="-Djava.awt.headless=true -server -Xms512M -Xmx1024M -XX:PermSize=256M -XX:MaxPermSize=512M"
If you're reading this, then you probably already have the intraLibrary 3.7 installation package. If you don't have the full installation package then please contact a member of the intrallect support team to organise this.
This package contains:
The intraLibrary web application needs access to the internet to perform some XML validation that occurs when using certain areas of functionality within intraLibrary.
The intraLibrary web application also needs to be able to send email from the application server. A valid, working and reachable smtp server must be defined. We will provide details on how to configure this later in the document.
This installation guide assumes that Tomcat 7, MySQL 5.1 and Java 1.7 have been correctly installed. We would recommend that you check both are working correctly before moving onto the installation of intraLibrary.
The basis of the intraLibrary web application is the intralibrary.war file. You can put this archive anywhere on the server, but we'd recommended it to be on the same physical volume as your Tomcat installation.
Once the web application is in place we can start to configure the properties to match your system.
Note: The intralibrary.war file is not designed to auto-deploy and you will experience problems if you place the file in the webapps directory of your Tomcat installation.
It is also recommended that you run IntraLibrary from an expanded war as it removes the need to add extra settings to Tomcat. It can be extracted using $JAVA_HOME/bin/jar -xvf intralibrary.war
All configurable aspects of intraLibrary (global properties, authentication, email content) are stored within a single config directory. This directory can be found at the root level of the installation package and should be copied to the filesystem somewhere (this can be anywhere on the file system). We strongly recommend that the directory is created outside of the webapp directory to ease the upgrade process in the future. The config directory should be accessible to the user that is used to start Tomcat. Once this directory has been copied we can go on to edit the global properties.
There are a number of properties that need to be defined in the config/intralibrary.properties file. The file supplied with the installation package contains some sample values.
The mandatory entries that need to be edited are:
Return address for any emails that are sent out. This should be set so the recipient can identify which instance of the application the mail refers to. For example intralibrary1@yourcompany.com
This is the name used to identify this instance of intraLibrary
Address for system admin ( report bugs, broken links etc ).
This needs to be a globally unique id used to identify this instance of intraLibrary. To avoid potential conflicts we suggest using an reverse internet naming scheme. For example com.your-company.intralibrary1
The optional entries that may be added to the properties file are:
This is the host name or ip address of the proxy that the application needs to be routed through.
This is the port that the proxy is listening on.
This property overrides the default entry page for all users. If this is not set, then all users will be taken to the browse library page. If you wish users to be taken to their upload area after login, then set this property to upload. This has no effect for users who do not have access to an upload area. The only valid values for this property are browse and upload.
This maintains the upper limit for objects stored in the application cache. The default is 250. Change this to higher values for improved performance on machines with a lot of physical memory or reduce it for machines with hardly any free memory.
The default is true. If you have a large cache size, then startup time for the application will be slowed down while the cache is populated. During debugging or testing, it may be useful to set this property to false. Note if the cache isn't populated at start up then the initial browsing and searching of object will run slowly.
The default is true. If you have a lot of objects in the repository, then startup time for the application will be slowed down while all the metadata for each object is indexed. During debugging or testing, it may be useful to set this property to false.
Determines the level, and quantity, of logging messages that will be output. Valid values are DEBUG, INFO, WARN, ERROR, FATAL
This restricts the file systems that intraLibrary has access to. These file systems are only relevant if intraLibrary is configured to allow importing from the file system.
This specifies the width, in pixels, of the big thumbnail shown on the image search results view. The thumbnail is scaled to the appropriate width whilst preserving the aspect ration. The default value for this property is 200. The maximum value for this property is 300
This specifies the width and height, in pixels, of the small thumbnail shown on the image search results view. The default value for this property is 75. The minimum value for this property is 30. The maximum value for this property is 200.
This specifies the quality of the thumbnail being displayed on the image search results view. The default value for this property is 7. The property is in the range 1-9, with 1 being the lowest quality and 9 being the highest. Note that the higher the quality the slower the rendering of the thumbnail.
This allows you to add an external stylesheet. See the integration guide for further details.
The licence file will be provided separately to the intraLibrary application, if you don't yet have a licence please contact a member of our support team.
To deploy the licence and ensure that it will be picked up by your intraLibrary installation the file intralibrary-licence.txt should be placed at the root level of the config directory which you created in the previous section.
For the rest of this section we will refer to the root directory of your Tomcat installation as TOMCAT_HOME. As mentioned earlier in the documentation if your TOMCAT_HOME has spaces in the path you will experience problems, so try to avoid this.
The intraLibrary web application needs to be registered to allow the application server to run it. There are multiple ways of doing this but we recommend creating a context descriptor in $CATALINA_HOME/conf/[enginename]/[hostname]/.
More information about configuring contexts can be found here: http://tomcat.apache.org/tomcat-7.0-doc/config/context.html
Included in this install package is a sample_context.xml file which you can use as a template for your installation. A brief explanation of some of the parameters follows below:
This attribute indicates where on your server the intralibrary web archive is located. Remember, we recommend that this should be on the same physical volume as the application server itself.
example: docBase="/disk1/tools/repositories/intralibrary.war"
This attribute indicates where on your server the config folder is located, you should only change the value part of this entry as any other changes will prevent the application from running successfully. Remember, we recommend that this folder lives outwith the web application.
example: <Environment name="configDir" type="java.lang.String" value="/Volumes/projects/intralibrary/config" override="true" />
This element indicates the fully qualified class name of the intraLibrary realm that the servlet container should use when authenticating against the intraLibrary context
The className attribute should not be changed, but the value of configDir should be exactly the same as the value of the configDir defined in the previous step.
NOTE: The following instructions are written specifically for creating a datasource using Tomcat 7, the MySQL 5.1 database engine and the database driver we supply. If you need more help with this then please feel free to contact a member of our support team.
To enable the communication between the application and the database, we need to create a datasource. We do this by making changes to the context we created in the section above, either prior to adding the context to the server.xml file or once the context is in place.
Inside the context element discussed above, you'll find a Resource element. You will need to specify the following attributes on the Resource element to setup the datasource. More information about configuring a datasource using Tomcat 7 can be found here:http://tomcat.apache.org/tomcat-7.0-doc/jndi-datasource-examples-howto.html
This is the connection string that the application would use to connect to the database. The example below will work fine as long as the database server is on the same machine as the application server and can by connected to as localhost. If the database server is not on the same machine as the application server, you will have to change the localhost part of the url, to the name, or IP address of the server the database resides on.
MySQL, by default, runs on port 3306. If your database engine runs on a different port then the port part of the url will obviously have to be changed.
The last part of the url before the '?' is the database name. Note that you must set jdbcCompliantTruncation=false.
If you wish to have full support for unicode characters and the utf-8 character set then set useUnicode=true and set characterEncoding=UTF8
E.g.
jdbc:mysql://localhost:3306/intralibrary?autoReconnect=true&jdbcCompliantTruncation=false&useUnicode=true&characterEncoding=UTF8
This is the maximum number of idle database connections that you wish to have in the database connection pool. For unlimited connections, set to 0.
example: 100
This is the maximum number of database connections in the pool. Set to 0 for no limit.
example: 500
This is the fully qualified name of the JDBC Driver class. If you are using the database driver we have supplied then the example value below will be fine.
example: com.mysql.jdbc.Driver
This is the maximum time to wait for a database connection to become available in ms, in this example 10 seconds. To wait indefinitely set this value to -1. An error will occur if the application has to wait for a time exceeding this limit.
example: 10000
This is the username that the application will use to connect to the database. This user must have read and write access to the database whose name is defined in the database connection url defined above.
example: intrallect
This is the password for the user defined above.
example: intrallect
Unless you are implementing a different database pool to the one supplied, leave this entry as is.
NOTE: The following instructions are written specifically for using Tomcat 7
The final part of configuring the datasource is to copy the following file from the install package dataSourceLib directory to TOMCAT_HOME/lib:
If you are prompted to overwrite any existing files, go ahead:
Although Tomcat already contains XML libraries, we need to make sure that the ones that are loaded are the ones that we need. To enable us to do this we make use of the ability to add jar files to an endorsed directory.
To achieve this you should create a directory called TOMCAT_HOME/endorsed and copy the following files from the install package endorsed directory to it.
To achieve this you should copy the following files from the install package authenticationLib directory to TOMCAT_HOME/lib. Again if you are prompted to overwrite existing files then go ahead:
Some of the entry points to intraLibrary are protected by authentication as provided by the servlet container to allow this authentication to function correctly a custom realm must be provided.
To achieve this you should copy the following files from the install package realmLib directory to TOMCAT_HOME/lib. Again if you are prompted to overwrite existing files then go ahead:
We need to create a database for the application to use. We do this by executing the following sql statement from the MySQL command line:
create database intralibrary;
you do not need to use the name intralibrary but the following instructions will assume you have.
Next we need to create a user for the application to connect to the database as and give that user the correct permissions. Here we are using the username/password of intrallect/intrallect. This can be set to anything you like but must match the values that were used when setting up the datasource.
grant all on intralibrary.* to intrallect identified by 'intrallect';
grant all on intralibrary.* to intrallect@'%' identified by 'intrallect'; On some database installations the wildcard ('%') does not work when connecting to the database from a machine which resolves as localhost. You can leave out this step if you are confident you can.
grant all on intralibrary.* to intrallect@'localhost' identified by 'intrallect';
We now need to create the database tables and populate these tables with the initial values that the application needs.
In the dbscripts folder, the main sql file that needs to be run to set up the database is: 'intralibrary.sql'.
There are a number of ways that this can be done. The easiest and most reliable is to connect to the database and from the database command line issue the following command:
source absolute/path/to/file; e.g. source /home/intralibrary/dbscripts/intralibrary.sql;
If you wish to add support for UKLomCore and CANCore application profiles, you should also run the uklomcore0p2.sql and cancore.sql files in this directory.
Although it is outside the scope of this documentation to go into a detailed discussion of database configuration, when using MySQL, the following advice may be useful.
MySQL configuration lives in a file named either my.cnf or my.ini. Its name and location depends on the installed environment. The following parameters (and numerous others) can be set in this file and effect performance of intraLibrary and should be investigated. We've included some sample values which we've found to work well but your environment may differ. For more information see here:http://dev.mysql.com/doc/refman/5.1/en/server-system-variables.html
Note:It is essential that the value for max_connections does not exceed the max_connections variable setup in the my.cnf(my.cnf) file for the MySQL server. If you are unfamiliar with this configuration file look here:http://dev.mysql.com/doc/refman/5.1/en/option-files.html
IntraLibrary will not operate if the MySQL server has been configured with the STRICT_TRANS_TABLE mode switched on. To switch this mode off, remove any reference to STRICT_TRANS_TABLE for the configuration file and restart MySQL.
We should now be ready to restart the application server and confirm that the intraLibrary application is running.
The first thing we need to do is to make sure we can see or read the output from the application server. Depending on how you set up the context, this output could go to one of a few places. By default, Tomcat writes all its logging to files inside TOMCAT_HOME/logs. If you have used the supplied sample_context.xml file then the output file you should be interested in is catalina.out.
Before you start the server make sure you have included the licence file in the correct place.
If you start the server now, and your logging level is set to the correct details, you should see some output to the log file that resembles the text below.
**************************************** application url:http://localhost application version:3.7(xxxxx) catalina home:/opt/tomcat/3p7 database server version:5.1.61-0ubuntu0.10.04.1 database driver:MySQL-AB JDBC Driver max database connections(0=unlimited):0 max upload file size:200 mb servlet container:Apache Tomcat/7.0.29 JVM file encoding:UTF-8 java version:1.7.0_05 java vendor:Oracle Corporation operating system:Linux,2.6.32-40-server os architecture:amd64 indexStore:file user name:root user language:en user country:GB user timezone:Europe/London java temp dir:/opt/tomcat/3p7/temp servlet temp directory:/opt/tomcat/3p7/work/Catalina/localhost/_ ---------------------------------------- configDir location:/opt/intralibrary/3p7/config http proxy:no proxy used mail host: admin email:admin@company.com error email:errors@company.com return email:intralibrary1@company.com id prefix:com.intrallect.poptart repository name:poptart object cache size:250 entry page:browse logLevel:INFO reindexOnStartup:true headless:true static http server running:false Integration with kaltura enabledregistered intraLibrary event handlers:com.intrallect.intralibrary.events.handlers.SimpleIntraLibraryEventHandler,com.intrallect.intralibrary.events.handler s.DefaultIntraLibraryEventHandler LoginPage class:com.intrallect.intralibrary.authentication.DefaultLoginPage ---------------------------------------- total memory assigned:512Mb maximum memory assigned:1024Mb ---------------------------------------- licence assigned to:company max contributors:1000000 version:3.7 expires:01-01-3000 ---------------------------------------- IntraLibrary started dd-MMM-yyyy hh:nn:ss ****************************************
Assuming that you have no errors in this output then congratulations, you have successfully installed intraLibrary 3.7.
If you don't see the output below then try browsing, through a web browser, to the newly defined context. If you see the intraLibrary login page then everything has been installed successfully
Now that you have a successful implementation of intraLibrary you can login using the username/password of intrallect/intrallect
Once the installation has been completed you should log in and set the application URL, this value is configured within the system section of the admin area (under 'System Options' tab) in the web interface.
The application URL determines the base url of the application e.g. http://localhost:8080/intralibrary and is used within the application when construction URLs are exposed outwith the web application e.g. URLs within SRU search results, RSS feeds, harvested result sets etc.
If this value is not set then intraLibrary's external facing interfaces will not be fully functional
To backup the Tomcat and IntraLibrary directories you can make a copy of them or use tools like tar. For the IntraLibrary database we do not recommend the use of mysqldump as the binary in the database can cause the backup to become corrupt. You should use the mysqlhotcopy command to backup the database. For more information on this see http://dev.mysql.com/doc/refman/5.1/en/mysqlhotcopy.html
If your installation of intraLibrary hasn't been successful then there are a number of initial steps that we would recommend you work through prior to contact the support team at Intrallect. For problems with the installation of specific tools (Tomcat, MySQL, etc) please read the relevant documentation.
The following list is by no means exhaustive, but is a useful set of diagnostics:
If you are still having trouble with your installation then please contact the Intrallect support team who will be happy to assist you.