Remote Server Configuration from within the server

This contains instructions to deploy from within a shell on the server. It contains instructions download the source, compile, package and deploy.

To build and package the WAR from within eclipse, please see Packaging the WAR from Eclipse.

Basic Components

The sharedrecords client application targets remote datastores through the use of a web application deployed on the Sun Java System Application server on which the datastore resides. To set up a server in this fashion, several components are required, the major ones being:

NOTE: a redhat distro VMWare image with Sun Java App server installed can be found here:  http://www.vmware.com/vmtn/appliances/directory/183.

  1. The Sun Java System Application Server (SJSAS) software. The SJSAS will contain other tools, such as Apache Ant and a recent (1.4.2 or higher) version of the JDK, which we will find useful if we decide to assemble and package the sharedrecords webservice locally on the machine. In particular, the SJSAS comes bundled with a JDK if you elect to download the Enterprise Edition of the SDK. SJSAS versions 8.1, 8.2 and 9.0 all seem to work with the web application.
  1. A "container", or http gateway into the SJSAS. This requirement is pretty lenient on what is considered an appropriate container. Apache HTTP Server 2.0 is known to work, and there is no reason to believe that Apache 1.3, Apache 2.2 or even Apache Tomcat will behave any differenly.

The web server simply needs to be started, and the SJSAS should integrate with it seamlessly. Make sure that ports 8080 (the client/user port), 8181 (an SSL port) and 4848 (the server admin) port are not blocked or firewalled by the maintainer of the machine.

  1. The sharedrecords web application. This is a collection of compiled .class files and configuration files packaged into a .war (web archive) file. You will need to deploy this on the SJSAS.

Webserver and Application Server Setup

To accomplish each of these in turn (starting with the webserver):

  1. This step is simple. Follow the installation directions of your favorite web server, as root. On Debian systems, this can be as easy as installing a single package. Add the server's bin/ directory to $PATH. If you are using the Apache HTTP Server, you can start and stop the server with 'apachectl start' and 'apachectl stop', respectively.
  1. If you do not have any version of the JRE (or the SDK, if you plan on packaging the web archive on the server), download an Enterprise Edition of the Standard Development Kit that contains a recent version of SJSAS, such as the Java 5 EE / Java 1.4 SDK at:

 http://java.sun.com/javaee/downloads/index.jsp

It's a good idea to install the SJSAS in /opt/SUNwappserver as the installer suggests. Do this all as root. During the installation, select all the standard ports, and remember the administrative password you have chosen. Add /opt/SUNWappserver/bin to your $PATH. The basic commands to

start and stop the SJSAS are 'asadmin start-domain domain1' and 'asadmin stop-domain domain1', respectively. Always stop the server before shutting down the machine, and remember to start it up when the machine boots.

To check that both servers are up and running and your ports are open, navigate to  http://localhost:8080/ in a browser. (Replace 'localhost' with the server's URL if you are doing this remotely.) Note that there is an administrative interface at  http://localhost:4848.

Creating the Web Archive

If the web archive (.war) file has already been provided to you, skip this step. Otherwise, you will have to assemble it using the code base in the repository. The end result of this is a packaged .war file that contains your web application and enough information about it for the SJSAS to deploy it. There is a bash shell script at

 https://www.sharedrecords.org/svn/sra/trunk/etc/execute.sh

that will do all of these steps for you. However, if you would like to do this by hand, follow these steps:

  • Configure the properties files. Point the etc/build.properties file to the correct paths / keywords. The admin username should be 'admin'. The j2ee home should be /opt/SUNWappserver , and the wscompile directory should be /opt/SUNWappserver/bin . Put the correct administrative password into etc/admin-password.txt . Copy the etc/server.policy file to /opt/SUNWappserver/domains/domain1/config . This file dictates the permissions of the web application. Since sharedrecords will be creating and deleting files, we'll want this (more permissive) server policy file, instead of the default.
  • Configure the *.xml webservice configuration files.
    • The most notable changes that need to take place are replacing every instance of "localhost" with the server's URL (in etc/config-wsdl.xml , etc/config-interface.xml , etc/webservices.xml and etc/org.sharedrecords.properties).
    • In org.sharedrecords.properties , comment out the "org.sharedrecords.OtherPropertyFiles?" property - it is only used by the client app.
    • Set the "org.sharedrecords.core.FileStoreRoot?" to something directory inside the space reserved for domain1 by the SJSAS - something like /opt/SUNWappserver/domains/domain1/applications/j2ee-modules/SRCStore/data_store will do.
    • Remember to create this directory if it does not exist.
  • Compile everything in /trunk/src/org/sharedrecords/core/ with the the "jaxrpc-*", "dom4j", "servlet" and "cos" jars on the classpath. Note that because we are not compiling the client application, we do not need any of the .jar files exclusively used by it. Put the .class files in build/. The ant task "build" in build.xml will do this step for you automatically.
  • Compile the webservice endpoint with wscompile. To do this, copy etc/config-interface.xml and etc/org.sharedrecords.properties to build/ and run

wscompile -define -mapping mapping.xml -d . -nd . -classpath . config-interface.xml

in the build/ directory. This step is done automatically by the ant "wscompile" task in build.xml

  • Create the .war file. Web archives are remarkably similar to .jar files in that they consist of a directory structure. Create a temporary directory called war/ .
    • Under war/WEB-INF/lib/ , place the "dom4j", "cos" and "jaxen" .jars.
    • Under war/WEB-INF/ , place the etc/sun-web.xml and etc/webservices.xml files.
    • Under war/WEB-INF/wsdl/ , place the newly-generated build/SRCDataStoreService.wsdl .
    • Under war/WEB-INF/build/ place the build/config-interface.xml and the newly-generated build/mapping.xml file, as well as *.class files, as they appear in the build/ directory.
    • Under war/ , place the etc/web.xml and etc/index.html files.
    • Under war/WEB-INF/classes/org/sharedrecords/core/utils , place the etc/org.sharedrecords.properties file.
    • You are now ready to package the web application.
    • Create a war file with war/web.xml as the webxml file, and include WEB-INF/*, build/*, org.sharedrecords.properties and index.html.

You will now have a file called SRCStore.war . The ant task "create-war" in build.xml will accomplish this step.

Deploying the web application

So you have an SRCStore.war file. Deployment is easy. Simply browse to  http://localhost:4848 , click on "Web Applications" in the left frame, select "Deploy..." and proceed from there. Alternately, you can do this on the command line with

asadmin deploy SRCStore.war --user admin --passwordfile etc/admin-password.txt --host localhost --port 4848 --asinstalldir /opt/SUNwappserver

Of course, replace 'localhost' with the machine's URL if you are deploying this remotely. Alternately, the ant task 'deploy' in build.xml will accomplish this step for you.

To make sure that you have deployed the application successfully, go to  http://localhost:8080/SRCDataStore/ .

Re-deploying

To put a newer version of the code (or configuration files, or server policy file, etc.) on the server, you will need to take the following steps:

  • Undeploy the old web application, through the administrative web interface ( http://localhost:4848)
  • Shut down the SJSAS. (asadmin stop-domain domain1)
  • Repackage the .war file. (asant -f build.xml create-war)
  • Restart the server (asadmin start-domain domain1)
  • Deploy the new .war file (asant -f build.xml deploy or  http://localhost:4848)