incubator-connectors-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kwri...@apache.org
Subject svn commit: r1214129 - /incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml
Date Wed, 14 Dec 2011 09:28:48 GMT
Author: kwright
Date: Wed Dec 14 09:28:48 2011
New Revision: 1214129

URL: http://svn.apache.org/viewvc?rev=1214129&view=rev
Log:
First crack at updating the documentation

Modified:
    incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml

Modified: incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml
URL: http://svn.apache.org/viewvc/incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml?rev=1214129&r1=1214128&r2=1214129&view=diff
==============================================================================
--- incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml
(original)
+++ incubator/lcf/branches/CONNECTORS-313/site/src/documentation/content/xdocs/how-to-build-and-deploy.xml
Wed Dec 14 09:28:48 2011
@@ -74,28 +74,49 @@
         <p></p>
         <p>The LGPL and proprietary connector dependencies are described in separate
sections below.</p>
         <p></p>
-        <p>The output of the ant build is produced in the <em>dist</em>
directory, which is further broken down by process.  The number of produced process directories
may vary, because optional individual connectors do sometimes supply processes that must be
run to support the connector.  See the table below for a description of the <em>dist</em>
folder.</p>
+        <p>The output of the ant build is produced in the <em>dist</em>
directory, which is further broken down by process.  (The number of produced <em>xxx-process</em>
directories may vary, because optional individual connectors do sometimes supply processes
that must be run to support the connector.)  See the table below for a description of the
<em>dist</em> folder.</p>
         <p></p>
         <table>
           <caption>Distribution directories</caption>
           <tr><th><em>dist</em> directory</th><th>Meaning</th></tr>
           <tr><td><em>web</em></td><td>Web applications
that should be deployed on tomcat or the equivalent, plus recommended application server -D
switch names and values</td></tr>
           <tr><td><em>processes</em></td><td>classpath
jars that should be included in the class path for all non-connector-specific processes, along
with -D switches, using the same convention as described for tomcat, above</td></tr>
-          <tr><td><em>lib</em></td><td>jars for all the
connector plugins, which should be referenced by the appropriate clause in the ManifoldCF
configuration file</td></tr>
+          <tr><td><em>connector-lib</em></td><td>jars
for all the connectors, referred to by properties.xml</td></tr>
           <tr><td><em>wsdd</em></td><td>wsdd files that
are needed by the included connectors in order to function</td></tr>
           <tr><td><em>xxx-process</em></td><td>scripts,
classpath jars, and -D switch values needed for a required connector-specific process</td></tr>
           <tr><td><em>script-engine</em></td><td>jars
and scripts for running the ManifoldCF script interpreter</td></tr>
+          <tr><td><em>multiprocess-example</em></td><td>scripts
and jars for an example that uses the multiple process model</td></tr>
           <tr><td><em>example</em></td><td>a jetty-based
example that runs in a single process (except for any connector-specific processes)</td></tr>
           <tr><td><em>doc</em></td><td>javadocs for framework
and all included connectors</td></tr>
           <tr><td><em>xxx-integration</em></td><td>pre-built
integration components to deploy on target system "xxx", e.g. Solr</td></tr>
         </table>
         <p></p>
-        <p>For all of the <em>dist</em> subdirectories above (except for
<em>wsdd</em>, which does not correspond to a process), any scripts resulting
from the build that pertain to that process will be placed in a <em>script</em>
subdirectory.  Thus, the command for executing a command under Windows for the <em>processes</em>
subdirectory will be found in <em>dist/processes/script/executecommand.bat</em>.
 (This script requires two variables to be set before execution: JAVA_HOME, and MCF_HOME,
which should point to ManifoldCF's home execution directory, described below.)  Indeed, everything
you need to run an ManifoldCF process can be found under <em>dist/processes</em>
when the ant build completes: a <em>define</em> subdirectory containing -D switch
description files, a <em>jar</em> subdirectory where jars are placed, and a <em>war</em>
subdirectory where war files are output.  </p>
+        <p>For all of the <em>dist</em> subdirectories above (except for
<em>wsdd</em>, which does not correspond to a process), any scripts resulting
from the build that pertain to that process will be placed in a <em>script</em>
subdirectory.  Thus, the scripts for the <em>filenet-processes</em> subdirectory
will be found in <em>dist/filenet-processes/script</em>.
+        (This script requires two variables to be set before execution: JAVA_HOME, and MCF_HOME,
which should point to ManifoldCF's home execution directory, described below.)  Indeed, everything
you need to run an ManifoldCF process can be found under <em>dist/processes</em>
when the ant build completes: a <em>define</em> subdirectory containing -D switch
description files, a <em>jar</em> subdirectory where jars are placed, and a <em>war</em>
subdirectory where war files are output.  </p>
         <p></p>
-        <p>The supplied scripts in the <em>script</em> directory for a
process generally take care of building an appropriate classpath and set of -D switches. 
(Note: none of the current connectors require special -D switches at this time.)  If you need
to construct a classpath by hand, it is important to remember that "more" is not necessarily
"better".  The process deployment strategy implied by the build structure has been carefully
thought out to avoid jar conflicts.  Indeed, several connectors are structured using multiple
processes precisely for that reason.</p>
+        <p>The supplied scripts in the <em>script</em> directory for a
process generally take care of building an appropriate classpath and setting necessary -D
switches.  (Note: none of the current connectors require special -D switches at this time.)
 If you need to construct a classpath by hand, it is important to remember that "more" is
not necessarily "better".  The process deployment strategy implied by the build structure
has been carefully thought out to avoid jar conflicts.  Indeed, several connectors are structured
using multiple processes precisely for that reason.</p>
         <p></p>
         <p>The <em>xxx-integration</em> directories contain components
you may need to deploy on the target system to make the associated connector function correctly.
 For example, the Solr connector includes plug-in classes for enforcing ManifoldCF security
on Solr 3.x and 4.x.  See the README file in each directory for detailed instructions on how
to deploy the components.</p>
-        
+        <p></p>
+        <p>Inside the <em>examples</em> directory, you will find everything
you need to fire up ManifoldCF in a single-process model under Jetty.  Everything is included
so that all you need to do is change
+            to that directory, and start it using the command <em>&lt;java&gt;
-jar start.jar</em>.  This is described in more detail later, and is the recommended
way for beginners to try out ManifoldCF.</p>
+        <p></p>
+        <p>ManifoldCF can also be deployed in a multi-process model.  Inside the <em>multiprocess-example</em>
directory, you will find everything you need to do this.  Below is a list of
+            what you will find in this directory.</p>
+        <p></p>
+        <table>
+          <caption>Multiprocess example directories</caption>
+          <tr><th><em>dist/multiprocess-example</em> directory</th><th>Meaning</th></tr>
+          <tr><td><em>web</em></td><td>Web applications
that should be deployed on tomcat or the equivalent, plus recommended application server -D
switch names and values</td></tr>
+          <tr><td><em>processes</em></td><td>classpath
jars that should be included in the class path for all non-connector-specific processes, along
with -D switches, using the same convention as described for tomcat, above</td></tr>
+          <tr><td><em>properties.xml</em></td><td>an
example ManifoldCF configuration file, in the right place for the multiprocess script to find
it</td></tr>
+          <tr><td><em>logging.ini</em></td><td>an example
ManifoldCF logging configuration file, in the right place for the properties.xml to find it</td></tr>
+          <tr><td><em>syncharea</em></td><td>an example
ManifoldCF synchronization directory, which must be writable in order for multiprocess ManifoldCF
to work</td></tr>
+          <tr><td><em>logs</em></td><td>where the ManifoldCF
logs get written to</td></tr>
+        </table>
+        <p></p>
+        <p>The basic multiprocess command scripts will be placed in the <em>processes/script</em>
subdirectory.  The script for executing commands is <em>processes/script/executecommand[.sh|.bat]</em>.
+            This script requires two environment variables to be set before execution: JAVA_HOME,
and MCF_HOME, which should point to ManifoldCF's home execution directory, where the <em>properties.xml</em>
file is found.)</p>
         <section>
           <title>Building the Documentum connector</title>
           <p></p>
@@ -342,16 +363,16 @@ cd dist/example
         <p></p>
         <p>An individual connector package will typically supply an output connector,
or a repository connector, or both a repository connector and an authority connector.  The
ant build script under <em>trunk</em> automatically forms each individual connector's
contribution to the overall system into the overall package.</p>
         <p></p>
-        <p>The basic steps required to set up and run ManifoldCF are as follows:</p>
+        <p>The basic steps required to set up and run ManifoldCF in multi-process mode
are as follows:</p>
         <p></p>
         <ul>
           <li>Check out and build, using "ant build".</li>
           <li>Install PostgreSQL.  The PostgreSQL JDBC driver included with ManifoldCF
is known to work with version 9.1, so that version is the currently recommended one.  Configure
PostgreSQL for your environment; the default configuration is acceptable for testing and experimentation.</li>
           <li>Install a Java application server, such as Tomcat.</li>
-          <li>Create a home directory for ManifoldCF.  To do this, make a copy of the
contents of <em>dist</em> from the build.  In this directory, create properties.xml
and logging.ini, as described above.  Note that you will also need to create a synchronization
directory, also detailed above, and refer to this directory within your properties.xml.</li>
-          <li>Deploy the war files in <em>&#60;MCF_HOME&#62;/web/war</em>
to your application server.</li>
-          <li>Set the starting environment variables for your app server to include
the -D commands found in <em>&#60;MCF_HOME&#62;/web/define</em>.  The
-D commands should be of the form, "-D&#60;file name&#62;=&#60;file contents&#62;".
 You will also need a "-Dorg.apache.manifoldcf.configfile=&#60;properties file&#62;"
define option, or the equivalent, in the application server's JVM startup in order for ManifoldCF
to be able to locate its configuration file.</li>
-          <li>Use the <em>&#60;MCF_HOME&#62;/processes/script/executecommand.bat</em>
command from execute the appropriate commands from the next section below, being sure to first
set the JAVA_HOME and MCF_HOME environment variables properly.</li>
+          <li>Change directory to <em>dist/multiprocess-example</em>.</li>
+          <li>Deploy the war files from <em>web/war</em> to your application
server.</li>
+          <li>Set the starting environment variables for your app server to include
any -D commands found in <em>web/define</em>.  The -D commands should be of the
form, "-D&#60;file name&#62;=&#60;file contents&#62;".  You will also need
a "-Dorg.apache.manifoldcf.configfile=&#60;properties file&#62;" define option, or
the equivalent, in the application server's JVM startup in order for ManifoldCF to be able
to locate its configuration file.</li>
+          <li>Use the <em>processes/script/executecommand[.bat|.sh]</em>
command from execute the appropriate commands from the next section below, being sure to first
set the JAVA_HOME and MCF_HOME environment variables properly.</li>
           <li>Start any supporting processes that result from your build.  (Some connectors
such as Documentum and FileNet have auxiliary processes you need to run to make these connectors
functional.)</li>
           <li>Start your application server.</li>
           <li>Start the ManifoldCF agents process.</li>
@@ -498,40 +519,6 @@ cd dist/example
           <p></p>
         </section>
         <section>
-          <title>Examples</title>
-          <p></p>
-          <p>An example properties file might be:</p>
-          <p></p>
-          <source>
-&#60;?xml version="1.0" encoding="UTF-8" ?&#62;
-&#60;configuration&#62;
-  &#60;property name="org.apache.manifoldcf.synchdirectory" value="c:/mysynchdir"/&#62;
-  &#60;property name="org.apache.manifoldcf.logconfigfile" value="c:/conf/logging.ini"/&#62;
-  &#60;libdir path="./lib"/&#62;
-&#60;/configuration&#62;
-          </source>
-          <p></p>
-          <p>An example simple logging configuration file might be:</p>
-          <p></p>
-          <source>
-# Set the default log level and parameters
-# This gets inherited by all child loggers
-log4j.rootLogger=WARN, MAIN
-
-log4j.additivity.org.apache=false
-
-log4j.appender.MAIN=org.apache.log4j.RollingFileAppender
-log4j.appender.MAIN.File=c:/dataarea/manifoldcf.log
-log4j.appender.MAIN.MaxFileSize=50MB
-log4j.appender.MAIN.MaxBackupIndex=10
-log4j.appender.MAIN.layout=org.apache.log4j.PatternLayout
-log4j.appender.MAIN.layout.ConversionPattern=[%d]%-5p %m%n
-          </source>
-          <p></p>
-          <p></p>
-          <p></p>
-        </section>
-        <section>
           <title>Commands</title>
           <p></p>
           <p>After you have created the necessary configuration files, you will need
to initialize the database, register the "pull-agent" agent, and then register your individual
connectors.  ManifoldCF provides a set of commands for performing these actions, and others
as well.  The classes implementing these commands are specified below.</p>
@@ -619,13 +606,13 @@ log4j.appender.MAIN.layout.ConversionPat
         <section>
           <title>Deploying the <strong>mcf-crawler-ui</strong>, <strong>mcf-authority-service</strong>,
and <strong>mcf-api-service</strong> web applications</title>
           <p></p>
-          <p>If you built ManifoldCF using ant under the <em>trunk</em>
directory, then the ant build will have constructed three war files for you under <em>dist/web</em>.
 Take these war
-              files and deploy them as web applications under one or more instances of your
application server.  There is no requirement that the <strong>mcf-crawler-ui</strong>,
<strong>mcf-authority-service</strong>, and <strong>mcf-api-service</strong>
web
+          <p>If you built ManifoldCF using ant, then the ant build will have constructed
three war files for you under <em>dist/multiprocess-example/web</em>.  If you
intend to run
+              ManifoldCF in multiprocess mode, you will need to deploy these web applications
on you application server.  There is no requirement that the <strong>mcf-crawler-ui</strong>,
<strong>mcf-authority-service</strong>, and <strong>mcf-api-service</strong>
web
               applications be deployed on the same instance of the application server.  With
the current architecture of ManifoldCF, they must be deployed on the same physical server,
however.</p>
           <p></p>
           <p>For each of the application servers involved with ManifoldCF, you must
set the following define, so that the ManifoldCF web applications can locate the configuration
file:</p>
           <p>-Dorg.apache.manifoldcf.configfile=&#60;configuration file path&#62;</p>
-          <p>Under <em>dist/web/define</em>, if it exists at all, you may
also see files that are not war files.  These files are meant to be used as command-line -D
switches for the application server process.
+          <p>Under <em>dist/multiprocess-example/web/define</em>, if it
exists at all, you may also see files that are not war files.  These files are meant to be
used as command-line -D switches for the application server process.
                 The switches may or may not be identical for the two web applications, but
they will never conflict.  You may need to alter environment variables or your application
server startup scripts in order to
                 provide these switches.  Luckily, no existing connectors require these at
this time.</p>
           <p></p>



Mime
View raw message