= CaTissue HowTo Build & Deploying CaTissue from the source code Tags: [[CaTissue]] [[OpenSpecimen]] 1) Download caTissue suite from caTissue site (https://gforge.nci.nih.gov/frs/?group_id=689) named with caTissue v1.2 installable[[BR]] 2) Once you have downloaded the caTISSUE_SUITE_v12_Installable_Pack.zip, extract the contents of the file to any directory.[[BR]] This folder contains two additional compressed files; caTissue_Suite_v1.2_Installable and caTissue_Suite_API_Client_v1.2_Installable[[BR]] 3) Unzip the caTissue_Suite_v1.2_Installable.zip, extract the contents of the file to any directory. [[BR]] 4) Unzip the caTissue_Suite_API_Client_v1.2_Installable.zip, extract the contents of the file to any directory.[[BR]] 5) In the installation folder caTissueInstall.properties is the Property file in which all the application configuration parameters are listed, we need to change it according to our local environment[[BR]] 6) In the installation folder build.xml is ANT script used to deploy the application on a JBoss server. This also creates the database schema for Oracle or MySQL.[[BR]] 7) In the installation folder SQL folder containing SQL scripts required for deployment[[BR]] 8) In the installation folder modules folder containing various caTissue modules[[BR]] 9) JBoss version should be 4.2.3 GA and Mysql version should be 5.0.45[[BR]] 10) In order to prevent lower case problem in ubuntu mysql you have to set set lower_case_table_names=1 in your /etc/mysql/my.cnf file. [[BR]] 11) Once above step is done shutdown the mysql server and restart it.[[BR]] 12) Before starting deployment make sure that jboss shouldn't be running.[[BR]] 13) Create the database first (eg: catissuecore) in mysql before starting of the building the application, as shown below,[[BR]] Drop DATABASE if exists catissuecore;[[BR]] [[BR]] CREATE DATABASE catissuecore;[[BR]] GRANT ALL PRIVILEGES ON catissuecore.* TO 'root'@'localhost' IDENTIFIED BY 'root' WITH GRANT OPTION;[[BR]] [[BR]] GRANT ALL PRIVILEGES ON catissuecore.* TO 'root'@'%' IDENTIFIED BY 'root' WITH GRANT OPTION;[[BR]] [[BR]] USE mysql;[[BR]] [[BR]] UPDATE User SET File_priv = 'Y' where User='root';[[BR]] [[BR]] FLUSH PRIVILEGES;[[BR]] [[BR]] 14) There seems to be a problem with a missing log4j.properties in the root config directory, so create an empty log4j.properties file in jboss-4.2.3.GA/server/default/catissuecore-properties[[BR]] 15) /usr/local/jboss/server/default/lib> mv hibernate3.jar hibernate3.jar.bak[[BR]] 16) /usr/local/jboss/bin> pico run.conf # set the jboss configuration options, MaxPermGen etc as per the catissue deployment guide[[BR]] 17) Start deploying the catissue application using build.xml with the argument deploy_all, if you see any error while in deployment because of upgrade_metadata_cnstrProp.sql then uncomment ALTER TABLE DYEXTN_COLUMN_PROPERTIES TYPE = INNODB; and ALTER TABLE DYEXTN_CONSTRAINTKEY_PROP TYPE = INNODB; in the same file. Start redeploying the application.[[BR]] 18) If you see any errors in building the application, once you resolved the issues freshly build the application with the arguments clean_server and delete_files (delete the previously created dependencies). Once this is done then you build the application with deploy_all.[[BR]] 19) Once build is successful war file will be automatically deployed into your jboss, start the jboss server.[[BR]] 20) Once the JBoss server is started, you can access the application using a web browser. The following is the URL pattern used for the application: http://machine_name:port_number/catissuecore.[[BR]] 21) When the browser displays the home page of caTissue Suite, you can log on to the application by specifying the values which were configured in first.admin.emailAddress and first.admin.password of caTissueInstall.properties before deployment.[[BR]] Following is the sample caTissueInstall.properties file[[BR]] -------------------------------------------------------[[BR]] [[BR]] #Enter absolute path of the installed directory of JBoss server {JBOSS_HOME}.[[BR]] #Please note that the path must be separated by Unix style path separator "/".[[BR]] jboss.home.dir=/home/localadmin1/jboss-4.2.3.GA[[BR]] [[BR]] #Please specify the server configuration name of jboss where you want to deploy.[[BR]] #By default it is set to 'default' configuration. This is useful if someone wants[[BR]] #to run multiple instances of suite application on same jboss.[[BR]] jboss.server.name=default[[BR]] [[BR]] #Enter server port on which JBoss is listing the client request[[BR]] # Please do not specify the port number in case of an Apache Front ended server[[BR]] #Default port is 8080[[BR]] jboss.server.port=8080[[BR]] [[BR]] #Hostname or IP address of the machine on which the JBoss server is running.[[BR]] #CAUTION: This parameter should not be set to localhost. Set the actual hostname or IP address[[BR]] jboss.server.host=localhost[[BR]] [[BR]] #Enter yes/no to specify Secure HTTP connection[[BR]] jboss.container.secure=[[BR]] [[BR]] #database type permissible values: oracle or mysql[[BR]] database.type=mysql[[BR]] [[BR]] #Hostname or IP address of the machine on which the database server is running.[[BR]] database.host=localhost[[BR]] [[BR]] #Port number to connect with the database server[[BR]] #Default port for MySQL : 3306[[BR]] #Default Port for Oracle: 1521[[BR]] database.port=3306[[BR]] [[BR]] #Oracle TNS name, applicable only when database.type=oracle[[BR]] oracle.tns.name=[[BR]] [[BR]] database.name=catissuecore[[BR]] database.username=root[[BR]] database.password=root[[BR]] [[BR]] #If CAS authentication server needs to be deployed on the[[BR]] #same server as caTissue (specified by jboss.home.dir), then set this property to "true"[[BR]] deploy.cas.on.catissue.jboss=true[[BR]] [[BR]] #If cas.deploy is "false", then fill the following CAS related properties:[[BR]] #Hostname or IP address of the machine on which the CAS server is running.[[BR]] #CAUTION: This parameter should not be set to localhost. Set the actual hostname or IP address[[BR]] cas.jboss.server.host=[[BR]] cas.jboss.port=[[BR]] #Enter yes/no to specify Secure HTTP connection for CAS[[BR]] cas.jboss.container.secure=[[BR]] #CAS is deployed on HTTPS server then Specify the .keystore file path of CAS server.[[BR]] cas.server.keystore.path=[[BR]] [[BR]] email.administrative.emailAddress=[[BR]] email.sendEmailFrom.emailAddress=[[BR]] email.mailServer=[[BR]] [[BR]] # Option to use the common package's email handler on server exception. Values = [true|false][[BR]] # Default = [false][[BR]] use.email.commonpackage.config=false[[BR]] # Send the exception email to e-addresses. Can have comma seperated values.[[BR]] email.sendEmailTo.emailAddress=[[BR]] # Admin Email address. This would be included in case above entry is empty or invalid.[[BR]] email.admin.support.emailAddress=[[BR]] # Email-From Name.[[BR]] email.sendEmailFrom.name=[[BR]] # The subject line of the email.[[BR]] email.exception.subject=System Exception Occured.[[BR]] [[BR]] #Application login timeout interval in minutes.[[BR]] #Default value is 30 minutes[[BR]] session.timeout=30[[BR]] #sets the addition info on home page[[BR]] app.additional.info=[[BR]] [[BR]] #Information related to first administrator account[[BR]] first.admin.department=d[[BR]] first.admin.institution=i[[BR]] first.admin.cancerresearchgroup=c[[BR]] first.admin.emailAddress=admin@admin.com[[BR]] first.admin.password=Login123[[BR]] [[BR]] #Enter path for the MMTx home directory[[BR]] caties.mmtx.home=[[BR]] [[BR]] #Values for DE API[[BR]] caCORE.jBoss.home.dir=[[BR]] caCORE.project.name=[[BR]] [[BR]] #Choose below option to associate dynamic extensions default clinical and pathology forms to the Collection Protocols.[[BR]] #Choose false to show all clinical and pathology default annotations for data entry[[BR]] #Choose true and edit the Show_Hide_Forms.xml present in the installable folder to associate selective forms to Collection Protocol for data entry[[BR]] show.hide.forms.based.on.CPs=false[[BR]] [[BR]] #URL needed for category creation.[[BR]] Application.url=[[BR]] [[BR]] #Set the location where caCore is generated[[BR]] cacore.deployable.location=./cacore_deployable[[BR]] [[BR]] #Comma separated Entity Groups which are to be excluded.[[BR]] exclude.entitygroup=[[BR]] [[BR]] #Comma separated Entity Groups which are only to be included.[[BR]] include.entitygroup=[[BR]] [[BR]] #Set the owner for the old saved queries prior to v1.2. Enter the login name of the user whom[[BR]] #you want to make the owner.[[BR]] saved.query.owner=[[BR]] [[BR]] #CSM DATABASE CREDENTIALS[[BR]] csm.database.type=[[BR]] csm.database.host=[[BR]] csm.database.port=[[BR]] csm.database.name=[[BR]] csm.database.username=[[BR]] csm.database.password=[[BR]] ---- == Update for CaTissue Plus deployed on LAMP servers == 1. The default version of Java installed on the LAMP v1 servers is OpenJDK 1.5 - this doesn't play well with JBoss. So we've additionally installed OpenJDK 1.7. This seems to work better, but requires that JBoss is started thus: > JAVA_HOME=/usr/java/jdk1.7.0_21/ /local/jboss/bin/run.sh -b 0.0.0.0 & This doesn't need to be done as root. on LAMP v2 servers, the default java is 1.7.0_21 so that should be OK. 2. The end user accesses a 'load balancer' by means of an alias: https://catissue-dev.lcbru.le.ac.uk which routes the request to the server itself at www15.lamp.le.ac.uk:80 - this machine only has port 80 accessible, so Apache is listening on port 80 and using mod_proxy and mod_proxy_http to reverse proxy to port 8080 for JBoss to pick up the request. {{{ From loadmodule.conf in the /local/apache2/etc directory: # Proxy to divert to the JBoss Application Server LoadModule proxy_module /usr/lib64/apache2-prefork/mod_proxy.so LoadModule proxy_http_module /usr/lib64/apache2-prefork/mod_proxy_http.so From httpd.conf in the /local/apache2/etc directory: # Proxy to provide access to the JBoss Application Server ProxyPass / http://localhost:8080/ ProxyPassReverse / http://localhost:8080/ }}} It works sufficiently to show the JBoss interface and the caTissue index page. NOTE THAT THIS APPROACH HAS BEEN REPLACED WITH mod_jk AS PER KRISHAGNI RECOMMENDATIONS The mod_jk approach requires: * mod_jk to be enabled in apache * a mod_jk.conf with configuration options: in /local/apache2/etc/mod.d/mod_jk.conf for our servers * a workers.properties with settings for the specific connection to jboss: in /local/apache2/etc/conf.d/workers.properties for our servers * a mod_jk_log (created automatically) * server.xml to define the jvmRoute to match the specified connection worker: in /local/jboss/server/default/deploy/jboss-web.deployer/server.xml for our servers 3. Originally I tried with jboss.server.host set to 'lcbru-catissue-dev.rcs.le.ac.uk' - this caused infinite redirect loops, and is bad. It isn't clear what this config setting is used for, and if it is used for building page URLs then the full alias is needed. I've changed this now to the actual IP address of the server itself (but this will not work if supplied to a browser as a link to a resource). It is now possible to log in to CaTissue. 4. There used to be an issue with flex / caused by the fact that https is used to connect to the load balancer, but the JBoss connection itself is not securely piped. That isn't a problem because it is all behind the firewall of the load balancer, but flex doesn't like it. The solution as documented on a number of websites is to edit WEB-INF/flex/services-config.xml: {{{ I changed my-secure-amf definition in services-config.xml to use a SecureAMFChannel but point to a non-secure AMFEndpoint. A re-compile and deploy solved the issue. false }}} Then do a 'jar cvf catissuecore.war *' in the home directory of the unpacked files and copy the resulting war file into the jboss directories. 5. Krishagni deployment notes https://catissueplus.atlassian.net/wiki/display/CAT/Deploying+caTissue+Plus == Settings for caTissueInstall.properties on LAMP v2 == jboss.home.dir=/local/jboss jboss.server.name=default jboss.server.port=8080 jboss.server.host=143.210.56.57 jboss.container.secure=no application.environment=LCBRU DEVELOPMENT email.mailServer=sendmail.le.ac.uk load.balancer.url=https://catissue-dev.lcbru.le.ac.uk/catissuecore == JBoss 5 == CaTissuePlus v3.0 is configured to work with JBoss 5, which is preferable to 4.2.3 When using JBoss 5, remember to put the following the JBoss run.sh. Especially the last parameter in blue. JAVA_OPTS="-Xms128m -Xmx1024m -XX:MaxPermSize=512m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false" Additionally, the security vulnerability (as below) must be addressed by deleting the admin console and the jmx console packages. We don't need them. == Comment out the LabelGenerator == By default CaTissue automatically assigns specimen labels and barcodes - this causes a problem with the API client. Following deployment of CaTissue, check that the jboss/server/default/catissuecore-properties/LabelGenerator.Properties file doesn't have the extra definitions which force barcode generation (i.e. comment out 'specimenLabelGeneratorClass' and 'specimenBarcodeGeneratorClass' and 'storageContainerLabelGeneratorClass') before running JBoss. == Update: Security vulnerability in JBoss == There is a known security vulnerability in JBoss, the JMX console to be precise, in certain versions of JBoss, including the one which CaTissue uses. It is imperative that when setting up JBoss on a server to deploy CaTissue, the JMX console is removed from the server, or patched as per http://java.dzone.com/articles/jboss-jmx-console Using the 'BRISSkit' package for JBoss - stored in the LCBRU artifact repository at http://lcbru-data.rcs.le.ac.uk/jboss/jboss-4.2.3.GA-brisskit-development.zip - will ensure the JBoss jmx console is not installed. Alternatively delete from the server/default/deploy directory the directories which deliver the jmx console and the admin console. == Ant optional jar == Running 'ant deploy_all' on a LAMP v2 server, results in a 'BUILD FAILED' message, because the ant optional packages are not installed. Installing the optional jar for the relevant ant version and then calling the process as "CLASSPATH=/local/ant/ant-nodeps-1.7.0.jar ant deploy_all" is a solution. Or, to re-deploy after config changes, use CLASSPATH=/local/ant/ant-nodeps-1.7.0.jar ant deploy_app == Home page image == CaTissuePlus includes the facility for a customised image on the home page. We have created three different ones, as attached to this page. Details of how to configure the image: https://catissueplus.atlassian.net/wiki/display/CAT/Configuration+To++Display+Institute+Logo+On+Home+Page Note that this requires a re-deploy of the app, which then implies checking the LabelGenerator.properties and the log4j.properties files. [[BackLinks]]