Installing on WebSphere

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Installation3.13.2

Table of Contents

• 1 Important Notes


• 2 Prerequisite: Creating a Myfaces v1.1 shared library


• 3 Prerequisite: Enabling Xalan as the standard JAXP Transformer


• 4 Configuring Share


• 5 Installing a License


• 6 Enabling WCM (Optional)


• 7 Configuring v3.2 and later
  
  
  
  • 7.1 Defining Environment Information
  
  
  • 7.2 Defining Database Connection Information the Websphere Way
  
  
  • 7.3 Defining Database Connection Information the Alfresco Way
  
  
  • 7.4 Installing the v3.2 EAR file
  
  


• 8 Configuring v3.1.1
  
  
  
  • 8.1 Installing the JDBC driver
  
  
  • 8.2 Defining Environment Information
  
  
  • 8.3 Installing the v3.1.1 EAR file
  
  


• 9 Removing SQL Warning messages from log file

Important Notes

Some of the configurations described here may not yet be supported by Alfresco support. See http://www.alfresco.com/services/support/stacks/ for the current list of supported stacks.

This page covers installation of Alfresco Enterprise versions 3.1.1 and later on Websphere 7.0.3. For older versions, please refer to the page Installing Older Versions on WebSphere.

It is very important that before commencing installation, you update Websphere with all applicable service packs, including WASSDK (embedded JDK) patches. This is because Alfresco's optimized I/O code requires the very latest patches available from IBM and will not function on an unpatched Websphere 7 installation.

Prerequisite: Creating a Myfaces v1.1 shared library

Because neither of the versions of JSF that ship with Websphere 7 are compatible with Alfresco, it is necessary to define a new isolated shared library in Websphere that contains a compatible implementation, as per option 2 in the Configuring JavaServer Faces implementation section of the Websphere 7 manual. Because the Alfresco Enterprise .ear file embeds an appropriate shared library definition in META-INF/ibmconfig, it is only necessary to prepare Websphere as follows:

1. Obtain the myfaces1_1-websphere-shared-lib.zip enterprise distributable from Alfresco and extract it to the root Websphere installation directory. This will create a myfaces1_1 directory containing all the .jars required by the myfaces1_1 shared library on Websphere. For example, on Windows:
   
   • cd /d 'C:\Program Files\IBM\WebSphere\AppServer'
     
   • java\bin\jar xvf myfaces1_1-websphere-shared-lib.zip
     

Prerequisite: Enabling Xalan as the standard JAXP Transformer

1. Copy the file $WAS_INSTALL_ROOT/java/jre/lib/jaxp.properties.sample (e.g. C:\Program Files\IBM\WebSphere\AppServer\java\jre\lib\jaxp.properties.sample) to $WAS_INSTALL_ROOT/java/jre/lib/jaxp.properties
   
2. Edit the file jaxp.properties as follows
   

 javax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl 
 javax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

Configuring Share

Because Websphere's default http port is 9080, it is normally necessary to provide custom configuration for the share application that points it to this port.

1. Obtain the file share-config-custom.xml.sample and copy it to $WAS_INSTALL_ROOT/lib/alfresco/web-extension/share-config-custom.xml (e.g. C:\Program Files\IBM\WebSphere\AppServer\lib\alfresco\web-extension\share-config-custom.xml).
   
2. Uncomment this section by removing the begin comment and end comment --> lines before and after it.
   

   
      <config evaluator='string-compare' condition='Remote'>
         <remote>
            <keystore>
                <path>alfresco/web-extension/alfresco-system.p12</path>
                <type>pkcs12</type>
                <password>alfresco-system</password>
            </keystore>
            
            <connector>
               <id>alfrescoCookie</id>
               <name>Alfresco Connector</name>
               <description>Connects to an Alfresco instance using cookie-based authentication</description>
               <class>org.springframework.extensions.webscripts.connector.AlfrescoConnector</class>
            </connector>
            
            <endpoint>
               <id>alfresco</id>
               <name>Alfresco - user access</name>
               <description>Access to Alfresco Repository WebScripts that require user authentication</description>
               <connector-id>alfrescoCookie</connector-id>
               <endpoint-url>http://localhost:8080/alfresco/wcs</endpoint-url>
               <identity>user</identity>
               <external-auth>true</external-auth>
            </endpoint>
         </remote>
      </config>
   

   
   


3. Globally replace all instances of 8080 in the file with 9080 (or your desired port number).
   
4. To work around ALF-4230, edit the file, so that a value of false is specified for the adobe-flash-enabled tag. E.g.
   

   
     <adobe-flash-enabled>false</adobe-flash-enabled>
   

   
   

Installing a License

If you have been issued with a .lic license file for this version of Alfresco, you should copy it to a $WAS_INSTALL_ROOT/lib/alfresco/extension/license directory (e.g. C:\Program Files\IBM\WebSphere\AppServer\lib\alfresco\extension\license\mylicense.lic).

Enabling WCM (Optional)

You will need the WCM bootstrap context on the class path.

1. Obtain the file wcm-bootstrap-context.xml and copy to $WAS_INSTALL_ROOT/lib/alfresco/extension (e.g. C:\Program Files\IBM\WebSphere\AppServer\lib\alfresco\extension).
   

Configuring v3.2 and later

This section covers the specifics of v3.2 and later versions. For v3.1.1, see #Configuring v3.1.1.

Defining Environment Information

This is done through the extension classpath mechanism and alfresco-global.properties.

1. Obtain the file alfresco-enterprise-sample-extensions.tar.gz or alfresco-enterprise-sample-extensions.zip and extract it to an empty directory.
   
2. From this directory, copy the file alfresco-global.properties.sample to $WAS_INSTALL_ROOT/lib/alfresco-global.properties (e.g. C:\Program Files\IBM\WebSphere\AppServer\lib\alfresco-global.properties)
   
3. Turn off the mbean server lookup by adding the following line
   

mbean.server.locateExistingServerIfPossible=false

Defining Database Connection Information the Websphere Way

In this section we will make use of Websphere's built-in connection pooling features with a MySQL database. If you are using another database type or simply would prefer to use the DBCP connection pool built in to Alfresco, please jump to the next section.

1. Log on to the WebSphere Administrative console, typically at http://localhost:9060/ibm/console/.
   
2. Expand Guided Activities in the top left panel and select Connecting to a database. Then follow each of the steps, supplying the parameters appropriate for your database to define a data source with JNDI name jdbc/alfresco.
   
3. In the Configure credentials for secure database access step, provide the user ID and password to your database account and give it the alias alfresco.
   
4. In the Configure a JDBC provider step, follow the instructions to create a new JDBC provider using the following properties:
   

   Name: MySQL JDBC Provider
   

   Description: MySQL JDBC Provider
   

   Class path: ${MYSQL_JDBC_DRIVER_PATH}/mysql-connector-java-5.0.3-bin.jar
   

   Implementation class name: com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource
   

   
   
5. In the Configure WebSphere variables step, define a MYSQL_JDBC_DRIVER_PATH variable holding the absolute path to the directory containing the MySQL JDBC driver.
   
6. In the Configure a data source step, click the MySQL JDBC Provider and then the Data sources link. Select New to create a new data source with the following parameters:
   

   Name: alfresco-datasource
   

   JNDI name: jdbc/alfresco
   

   
   
7. Select Use this data source in container managed persistence (CMP).
   
8. Make sure that the generic data store helper (com.ibm.websphere.rsadapter.GenericDataStoreHelper) is selected.
   
9. Select alfresco as the Component-managed authentication alias.
   
10. Select OK to save the data source.
    
11. Add the following custom properties:
    

    databaseName: alfresco?autoReconnect=true
    

    port: 3306
    

    serverName: localhost
    

    
    

Defining Database Connection Information the Alfresco Way

As an alternative to the above:

1. Copy your JDBC driver jar to ${WAS_INSTALL_ROOT}/lib (for example, C:\Program Files\IBM\WebSphere\AppServer\lib).
   
2. Uncomment and edit the lines appropriate for your database type in the alfresco-global.properties file you set up previously. See  Database Configuration for more information.
   

Installing the v3.2 EAR file

1. Obtain the v3.2 alfresco-enterprise.ear enterprise distributable from Alfresco. This embeds the alfresco and share web applications plus the necessary Websphere configuration to use the myfaces1_1 shared library with parent-last loading order.
   
2. Log on to the WebSphere Administrative console, typically at http://localhost:9060/ibm/console/.
   
3. Navigate to Applications > New Application > New Enterprise Application
   
4. Browse to alfresco-enterprise.ear on the local file system and click 'Next'
   
5. Select 'Detailed - Show all installation options and parameters' and click 'Next'
   
6. Jump to the 'Map resource references to resources' step you will see highlighted with a (+)
   
7. Under 'Target Resource JNDI Name', type jdbc/alfresco then click 'Next'. If you followed #Defining Database Connection Information the Websphere Way this will map to the datasource you set up earlier. Otherwise, Alfresco will fall back to the database connection configuration in alfresco-global.properties (see #Defining Database Connection Information the Alfresco Way). If you want to force Alfresco not to use a Websphere datasource, you can enter any invalid path such as jdbc/dummy.
   
8. Jump to the 'Map environment entries for Web modules' step.
   
9. For 'properties/dir.root', specify an absolute filesystem path where you would like Alfresco file data to be stored, e.g. 'C:\alf_data'
   
10. You may leave the Hibernate properties blank unless you want to override the default behaviour, where they will be auto-detected.
    
11. Click 'Next' and 'Finish'
    
12. Save your profile changes to the master repository
    
13. Restart the Websphere server. This time Alfresco should start with it and you should be able to log in at http://localhost:9080/alfresco or http://localhost:9080/share
    

Configuring v3.1.1

Installing the JDBC driver

Copy your JDBC driver jar to ${WAS_INSTALL_ROOT}/lib (for example, C:\Program Files\IBM\WebSphere\AppServer\lib).

Defining Environment Information

As with older Alfresco versions, this is done through the extension classpath mechanism.

1. Obtain the following files and save them to $WAS_INSTALL_ROOT/lib/alfresco/extension (e.g. C:\Program Files\IBM\WebSphere\AppServer\lib\alfresco\extension):
   
   1. custom-repository-context.xml
      
   2. custom-repository.properties
      
   3. custom-hibernate-dialect.properties
      
2. Edit custom-repository.properties and custom-hibernate-dialect.properties so that the parameters are suitable for your installation, in particular specifying a suitable value for the dir.root location.
   

Installing the v3.1.1 EAR file

1. Obtain the v3.1.1 alfresco-enterprise.ear enterprise distributable from Alfresco. This embeds the alfresco and share web applications plus the necessary Websphere configuration to use the myfaces1_1 shared library with parent-last loading order.
   
2. Log on to the WebSphere Administrative console, typically at http://localhost:9060/ibm/console/.
   
3. Navigate to Applications > New Application > New Enterprise Application
   
4. Browse to alfresco-enterprise.ear on the local file system and click 'Next'
   
5. Select 'Fast Path - Prompt only when additional information is required.' and click 'Next'
   
6. Click 'Next' until a 'Finish' button appears
   
7. Save your profile changes to the master repository
   
8. Restart the Websphere server. This time Alfresco should start with it and you should be able to log in at http://localhost:9080/alfresco or http://localhost:9080/share
   

Removing SQL Warning messages from log file

Websphere will show warnings in the log file like:


[12/7/10 17:24:42:206 EET] 0000003a JDBCException W  org.hibernate.util.JDBCExceptionReporter logWarnings SQL Warning: 4474,  SQLState: 01000

[12/7/10 17:24:42:208 EET] 0000003a JDBCException W  org.hibernate.util.JDBCExceptionReporter logWarnings  [jcc][t4][10217][10310][4.8.87] Connection read-only mode is not  enforceable after the connection has been established.  To enforce a read only connection, set the read-only data source or connection property. ERRORCODE=4474, SQLSTATE=01000


The current driver's implementation will throw these warnings, which have no impact on the operation of Alfresco. These warnings can either be ignored, or the logging can be configured to stop showing these:

• Open WAS management console 
  
• Navigate to Troubleshooting->Logs and trace- Server - Change Log Detail Levels  
  
• Search for org.hibernate.util.* component 
  
• Set org.hibernate.util.JDBCExceptionReporter class logger - Messages and Trace Levels to 'severe' or 'fatal'