Deploy/container/Tomcat
From Omar Wiki
This page describes how to use Apache Tomcat web container for deploying freebXML Registry server code.
Contents |
Overview and Concepts
Apache Tomcat is a commonly used open source web container.
Known Versions Supported
- 5.0.28
- 5.0.19
- 5.5.7
Deployment of omar to Tomcat
- Shutdown Tomcat first: ./build.sh stop.tomcat
- Deploy to Tomcat: Type "build deploy" in <omar.basedir>. It will create a Web application "omar" in Tomcat with all the required files.
- The database connection properties in build.properties is irrelevant after deployment to Tomcat. In case you need to change something, either change build.properties and re-deploy or change the omar.xml deployment descriptor in <TOMCAT_HOME>/conf/Catalina/localhost
- If you want to enable debugging output, one option is to set the environment variable CATALINA_OPTS to -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog . You can set the variable e.g. in the Tomcat startup script. See SimpleLog and Commons Logging for more options that you can configure.
- Configure HTTPS support for Tomcat, with RegistryOperator as trusted certificate authority. This step is required for user registration and publishing through Web UI. See Enabling HTTPS in Tomcat.
- Restart Tomcat:
- ./build.sh start.tomcat #Starts without enabling JPDA debugging
- ./build.sh jpda.tomcat #Start with JPDA debugging enabled. This allows connecting being able to debug server code using an IDE like NetBeans
Enabling HTTPS in Tomcat
Quickstart instructions are as follows:
- Generate key for Tomcat, password value of "changeit":
keytool -genkey -alias tomcat -keyalg RSA
This generates a RSA key with alias "Tomcat" at default keystore location (${user.home}/.keystore). Alternatively, you can run "ant genKeys.tomcat" target, which will do the same.
Note: Tomcat uses javax.net.ssl.KeyManagerFactory and that requires same password for keystore and all contained keys - init method will try loading each key with (same) provided password.
- Uncoment and fix the SSL Connector in tomcat/conf/server.xml:
<Connector port="8443" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" debug="0" scheme="https" secure="true" clientAuth="want" sslProtocol="TLS" truststorePass="changeit" truststoreType="jks" truststoreFile="$OMAR_HOME/data/security/appserver-truststore.jks"/>
NOTE: you must replace $OMAR_HOME in the connector configuration. The trustore is generated by the genKeys target and its location is set by omar-setup.security.appserverTruststoreFile build-time property.
By defining clientAuth="want", you set the server to request a certificate from the client web browser. The server will provide a list of trusted CAs - which should include our RegistryOperator. If client web browser finds a match (a certificate signed by one of the CAs contained in truststoreFile), that will be sent to server.
Server will then check for a registered user corresponding to the given certificate and if, again, there is a matching certificate in the omar.security.keystore, client will be authenticated as the correponding user. Otherwise (unknownn or no certificate), the client will not be athenticated and will use RegistryGuest credentials.
For more information check the instructions in http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html (plus you might have a copy of the Tomcat documentation in $JWSDP_HOME/docs/tomcat).
The instructions lead you through making a key and editing Tomcat's server.xml file to configure HTTPS support. Using the Correct Port for HTTPS
Use Endorsed Jars?
Having problems with xerces or xalan jar version mismatch? You may need to use or not use the java endorsed mechanism withthe JDK and or tomcat.
For JDK 5 make sure that there are no jars in the <catalina.home>/common/endorsed directory. For JDK 1.4 make sure follow instructions in red color at http://ebxmlrr.sourceforge.net/3.0/SetupGuide.html#System%20Requirements
Special Instructions When Deploying to Tomcat 5.5.x
By default omar is configured in a manner compatible with Tomcat 4.0.x and Tomcat 5.0.x. If you are using Tomcat 5.5.x (e.g. as in bundled tomcat version of Tomcat in NetBeans 5.0), then the following notes decsribe special instructions when using Tomcat 5.5.x:
- change catalina.home in build properties to point to the new location of Tomcat.
- you might have to define catalina.base if your tomcat is shared (like the one that comes with Netbeans) (NOT TESTED!)
- uncomment the following property from build.properties:
#appserver-jndi-context.filename=jndi-context-5.5.x.xml
When Deploying to Tomcat 5.5.20+
If you are using a version at 5.5.20 or above there is a bug referenced here. There are two choices:
- Make sure there are no spaces in the path to the Tomcat directory.
- Place the following element in the web.xml.template file located in the <omar.home>/conf directory:
<listener> <listener-class>com.sun.faces.config.ConfigureListener</listener-class> </listener>
Special Instructions When Deploying to Tomcat 6.x
TBD.
Customizing Ports Used By Tomcat
You can change the ports used by Tomcat, and by the registry by editing the server.xml file in <tomcat-home>/conf and by reflecting that edit in <omar-home>/omar build.properties.
- change port="xxxx instances in server.xml from the 8080 sequence to a consistent sequence such as "6480", for instance changing <Connector port="8080"...> to <Connector port="6480"...> making sure to change all instances to be avoid later conflicts if original numbers are later uncommented to activate other options.
- change omar.container.url=http://localhost:8080" to omar.container.url=http://localhost:xx80' where the first two digits of the port number reflect the new sequence used in tomcat's server.xml file.
- when this was tested, it required shutting the entire system down and rebooting. It is not clear if this is OS and system specific.
