Installation

1. Application Server version

   PageBox exists in three flavors:
   1. Application server version tested with Tomcat and Resin
   2. Embedded server (OSGi) version tested with Sun JES 2
   3. Diskless embedded server version also tested with Sun JES 2

   In this document, we describe only Application server version for two reasons:

   • We didn't test the repository/embedded server integration version
   • The embedded server installation guide should describe concepts such as bundles that don't exist in Application server world. For that reason, the installation on an embedded server is likely to be described in a different document.

   For questions regarding embedded server and diskless embedded server version please contact support@pagebox.net.

   In the same way PageBox can be ported to other Application servers. We simply chose to focus on Tomcat and Resin because both are free for development and deployed by some ASPs.

2. Roles

   1. Host

      

      A PageBox host is not necessarily an ASP. On Internet it can be any host with a static IP address and preferably a synchronous link. On Intranet it can be any server.

      An Application Server, Tomcat or Resin must be installed and the installation process consists of installing PageBox on this Application Server.

   2. Repository

      

      A PageBox repository is essentially a well-known point where:

      • PageBoxes subscribe to get published presentations
      • Presentation providers publish their presentations

      PageBox repository (also described as Publisher on this site) is implemented in a set of servlets. Therefore the repository also requires an Application server. As it is a set of very standard servlets it should run in any Servlet 2.2 conformant application server.

      The repository installation consists of installing a PublisherServer package on this Application Server.

   3. Presentation provider

      The Presentation provider publishes presentations on repositories.
      For that, it needs to install a small JFC application, PublisherClient.

   4. Developer

      A PageBox presentation is:

      • either just a regular Web archive
      • or a set of Cocoon XML (XSP) and XSL files

      For Web archives there are minor restrictions listed in Application server documentation.
      Cocoon support is new and we didn't identify and listed yet possible restrictions.

      We recommend developers to install a PageBox (to act as a PageBox host) at least for QA tests. As PageBox includes servlets allowing installing archives (acting as a repository), developers don't need to install PublisherServer and PublisherClient.

      We put in blue no-brainer fast installation instructions.

3. Host installation

   1. Application server installation

      You need to perform this step only if the Application server is not already installed - for instance by your ASP.

      Download Tomcat from http://jakarta.apache.org or Resin from http://www.caucho.com.
      We assume in the next section that you unpack the Application server in a $ASDir directory.
      Read the Application server documentation and configure it according to your needs. The decisions that you have to take at this step are outside the scope of PageBox.

   2. Configurator installation and use

      Download configurator.war in $ASDir/webapps and restarts the Application server.

      If you didn't change the Application server listening port and if your are on the machine where the Application server runs, set your browser to http://localhost:8080/configurator/JSPservletConfig.
      Set ID to whatever you want - typically the name of your machine and Cache path to the directory where you want to install the PageBox. We name later that directory $PageBoxDir. The directory doesn't need to exist but the Application server must be able to create and update it.
      Click on the Check button. It will update other fields according to Cache path.

      For the next step, you need to be connected on Internet. Click on the Set button. It should take a while - especially if you have a modem connection - as the configurator downloads 3.8MB.

      If your connection fails during the download, simply restart JSPservletConfig | Set.
      If you want to know more about the configurator, look at its documentation.

      Check for errors at the bottom of the screen:

      

      If you have the errors above, check your connection to Internet.

      If you have no error, you successfully installed PageBox.
      Support archives are in $PageBoxDir/lib.
      The web.xml and the cocoon.properties configurations are in $PageBoxDir/WEB-INF.

   3. Context setting

      You need now to update your Application server configuration.
      First stop it.

      In case of Tomcat, open $ASDir/conf/server.xml with an editor (Notepad and vi are OK).
      Add just before <!-- Virtual host example -

      <Context path="/PageBox"
          docBase="$PageBoxDir">
      </Context>

      In case of Resin, open $ASDir/conf/resin.conf with an editor (Notepad and vi are OK).
      Add just before </host>

      <web-app id='/PageBox' app-dir='$PageBoxDir'/>

      The bolded PageBox will be in the url you will use to invoke a servlet or xml handled by this PageBox.
      Suppose that you deploy a presentation named myArchive, to invoke myServlet stored in this archive you will use:
      http://localhost:8080/PageBox/myArchive/myServlet.

      $PageBoxDir should be the full path of your PageBox directory.

      Now the PageBox installation is completed. You can restart your Application server.

   4. Optional steps

      The distribution includes:

      • Cocoon 1.8.2
      • Soap 2.1
      from Apache.
      You can remove them. In that case, update $PageBoxDir/WEB-INF/web.xml:
      <init-param> <param-name>ClassPath</param-name>
      <param-value>
      $PageBoxDir/lib/InputSource.jar;$PageBoxDir/lib/xerces_1_2.jar; $PageBoxDir/lib/turbine-pool.jar;$PageBoxDir/lib/w3c.jar;$PageBoxDir/lib/bsf.jar; $PageBoxDir/lib/xalan_1_2_D02.jar;$PageBoxDir/lib/fop_0_15_0.jar;$PageBoxDir/lib/cocoonPatch.jar; $PageBoxDir/lib/cocoon.jar;$PageBoxDir/lib/xml.jar;$PageBoxDir/lib/activation.jar; $PageBoxDir/lib/mail.jar;$PageBoxDir/lib/soap.jar;$PageBoxDir/lib/loopback.jar; $PageBoxDir/lib/cocoonSupport.jar
      </param-value>
      <description>policy file for archives without explicit policy</description>
      </init-param>

      If you remove cocoon ($PageBoxDir/lib/cocoonPatch.jar), also remove $PageBoxDir/lib/cocoonPatch.jar.
      If you remove Xerces ($PageBoxDir/lib/xerces_1_2.jar), also remove $PageBoxDir/lib/InputSource.jar

      You may want to add other archives:

      • To use SOAP over SMTP. Then you need to install JavaMail 1.2 from Sun and add its libraries both in $PageBoxDir/lib and in <param-value>
      • To support proprietary protocols

   5. Installation verification
      1. On your browser go to http://localhost:8080/PageBox/ServletUpdate.
      2. Ask for the installation of demo.jar stored on http://pagebox.net. You should have something like this:

         

      3. Click on Update/Create. You should get something like this:

         

      4. The demo installation is completed.

         Enter http://localhost:8080/PageBox/demo/first.htm. You should get this form:

         

         Query is whatever you want. It is a string sent to the web service.
         Url is the web service URL, http://localhost:8080/PageBox/loopbackHTTP to invoke the embedded loopback server.
         After you clicked on submit, you should get this:

         

      5. Go back first.htm form.

         

         Now select SOAP on the list. Url is the SOAP router URL, http://localhost:8080/PageBox/rpcrouter to invoke the embedded SOAP router. You should get this:

         

         What happend?
         The message contains an Error element with the rpcrouter message. The SOAP loopback service is not registered.

         Create a DeploymentDescriptor.xml like this:

         <?xml version="1.0"?> <isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
             id="urn:loopbackSOAP">
           <isd:provider type="java"
             scope="Request"
             methods="getDocument">
             <isd:java class="loopback.loopbackSOAP"/>
           </isd:provider>
           <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
         </isd:service>

         Register the SOAP service with this command:

         java org.apache.soap.server.ServiceManagerClient
         http://localhost:8080/PageBox/rpcrouter deploy DeploymentDescriptor.xml

         Retry your request. You should get this:

         

      6. Subscription

         To install a repository see the next part.

         Let's assume your repository is at the URL http://Repository.
         On your browser go to http://Repository/publish.
         Enter your URL - without the archive and servlet name. You don't need to enter http://. You should have something like:

         

         Click on subscribe. You should get this:

         

         If archives were already published on that repository, they will be automatically deployed on your PageBox.
         You can check them with ServletUpdate.

      7. Administration overview

         

         For more information, click on the administration component that you wants to check.

   6. Repository installation

      1. Application server installation

         You need to perform this step only if the Application server is not already installed - for instance by your ASP

         Download Tomcat from http://jakarta.apache.org or Resin from http://www.caucho.com.
         We assume in the next section that you unpack the Application server in a $ASDir directory.
         Read the Application server documentation and configure it according to your needs. The decisions that you have to take at this step are outside the scope of PageBox.

      2. Configurator installation and use

         Download configurator.war in $ASDir/webapps and restarts the Application server.

         If you didn't change the Application server listening port and if your are on the machine where the Application server runs, set your browser to http://localhost:8080/configurator/PublishConfig.

         You must set two fields:

         • Repository directory
         • Repository URL

         These two fields must match: you must be able to download a file File stored in Repository directory/File using the url Repository URL/File.

         Click check. It will update other fields according to Repository directory
         You should have something like this:

         

         Now click on Set. Check for errors at the bottom of the screen:

         

         If you have the errors above, check your connection to Internet.

         If you have no error, you successfully installed a PageBox repository.
         The web.xml configuration is in Repository directory/WEB-INF.

      3. Administration overview

         

         For more information, click on the administration component that you wants to check.

   7. Content provider installation

      1. Publisher client installation

         You must have installed JDK 1.3 and set your PATH.
         Download PublisherClient.jar on your computer.

         Update your CLASSPATH.

         • On Windows: set CLASSPATH=PublisherClient.jar;%CLASSPATH%
         • On Unix or Linux something like (depending on your shell):CLASSPATH=PublisherClient.jar:$CLASSPATH

      2. Publisher client use

         Start the Publisher client with the command:

         java PublisherClient.PublisherClient

         You should get that display:

         

         Click on the Select Archive button. Then select the archive to publish:

         

         If you get this:

         

         your archive is published