[jbpm-commits] JBoss JBPM SVN: r5820 - in jbpm4/trunk/modules: userguide/src/main/docbook/en/modules and 1 other directory.

Author: jbarrez Date: 2009-10-27 12:56:05 -0400 (Tue, 27 Oct 2009) New Revision: 5820 Modified: jbpm4/trunk/modules/distro/src/main/files/install/build.xml jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml Log: Revised documentation of chapter 2 Modified: jbpm4/trunk/modules/distro/src/main/files/install/build.xml =================================================================== --- jbpm4/trunk/modules/distro/src/main/files/install/build.xml 2009-10-27 16:27:14 UTC (rev 5819) +++ jbpm4/trunk/modules/distro/src/main/files/install/build.xml 2009-10-27 16:56:05 UTC (rev 5820) @@ -191,7 +191,7 @@ <!-- ### CREATE USER WEBAPP ########################################## --> <target name="create.user.webapp" depends="create.cfg" - description="Generates a configuration in dir generated/cfg"> + description="Generates a configuration in dir /install/generated/user-webapp"> <delete dir="${jbpm.home}/install/generated/user-webapp" /> <mkdir dir="${jbpm.home}/install/generated/user-webapp/WEB-INF/classes" /> <mkdir dir="${jbpm.home}/install/generated/user-webapp/WEB-INF/lib" /> @@ -797,7 +797,6 @@ <mkdir dir="${signavio.tmp.dir}" /> <unzip src="${jbpm.home}/install/src/signavio/${signavio.war.file.name}" dest="${signavio.tmp.dir}" /> - <!-- Replace Windows backslash with forward slash (see JBPM-2540) --> <pathconvert property="signavio.repo.path" targetos="unix"> <map from="${basedir}/" to='' /> Modified: jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml =================================================================== --- jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml 2009-10-27 16:27:14 UTC (rev 5819) +++ jbpm4/trunk/modules/userguide/src/main/docbook/en/modules/ch02-Installation.xml 2009-10-27 16:56:05 UTC (rev 5820) @@ -3,15 +3,16 @@ <section id="thedistribution"> <title>The distribution</title> - <para>Just unzip the jBPM download to some location on your hard drive. + <para>Unzip the jBPM download (<literal>jbpm-4.X.zip</literal>) to some location on your hard drive. You'll see following subdirectories: </para> <itemizedlist> <listitem><literal>doc</literal>: User guide, javadocs and developers guide</listitem> <listitem><literal>examples</literal>: Example processes that are used in the user guide</listitem> - <listitem><literal>install</literal>: Installation scripts</listitem> + <listitem><literal>install</literal>: Installation scripts for several environments</listitem> <listitem><literal>lib</literal>: Third party libs and some special jBPM libraries</listitem> - <listitem><literal>src</literal>: Sources</listitem> + <listitem><literal>src</literal>: Source files</listitem> + <listitem><literal>migration</literal>: see developers guide</listitem> <listitem><literal>jbpm.jar</literal>: The jBPM main library archive</listitem> </itemizedlist> </section> @@ -31,10 +32,11 @@ <para>The <emphasis role="bold">demo setup</emphasis> is the simplest way to get started. This section describes the steps to complete the demo setup. </para> - <para>If you have previously downloaded jboss-5.0.0.GA.zip, create a downloads directory - in your <literal>${jbpm.home}/install/downloads</literal> directory and place the zip file in - there. Otherwise the script will download it for you. The same is true for eclipse-jee-galileo-win32.zip - (or eclipse-jee-galileo-linux-gtk(-x86_64).tar.gz on Linux and eclipse-jee-galileo-macosx-carbon.tar.gz on Mac OSX) + <para>If you have previously downloaded <literal>jboss-5.0.0.GA.zip</literal>, you can drop it + in the <literal>${jbpm.home}/install/downloads</literal> directory. + Otherwise the script will download it for you, but it will take some time (depending on your connection). + The same is holds for eclipse-jee-galileo-win32.zip (or eclipse-jee-galileo-linux-gtk(-x86_64).tar.gz on Linux + and eclipse-jee-galileo-macosx-carbon.tar.gz on Mac OSX) </para> <para>Open a command prompt and go do directory <literal>${jbpm.home}/install</literal>. Then run @@ -52,12 +54,20 @@ <listitem>Create an examples.bar business archive from the examples and deploy it to the jBPM DB.</listitem> <listitem>Load the example users and groups from <literal>${jbpm.home}/install/src/demo/example.identities.sql</literal> </listitem> <listitem>Install eclipse into <literal>${jbpm.home}/eclipse</literal></listitem> + <listitem>Install the jBPM web console</listitem> + <listitem>Install the Signavio web modeler</listitem> <listitem>Start eclipse</listitem> </itemizedlist> - <para>After this is done JBoss will be running in the background. Once eclipse has started, you can continue - to follow the instructions of <xref linkend="graphicalprocessdesigner" /> + <para> + After this is done, JBoss will be running in the background. Once + eclipse has started, you can continue to follow the instructions of + <xref linkend="graphicalprocessdesigner" /> to start coding your jBPM business processes. </para> - <para>And you can surf to <ulink url="http://localhost:8080/jbpm-console">the jBPM console</ulink> + <para> + Or you can start modeling processes through + <ulink url="http://localhost:8080/jbpmeditor/p/explorer">the Signavio web editor</ulink>. + </para> + <para>Or surf to <ulink url="http://localhost:8080/jbpm-console">the jBPM console</ulink>. You can login as one of the following users: </para> <table><title>Example console users:</title> @@ -88,17 +98,22 @@ </tbody> </tgroup> </table> - <para>Known limitation: Currently, the timeout of the console is too tight for - the reporting to initialize. So the first time when you access the reporting - the request will timeout and the console crashes. Logging out and login again works around - this problem. It's being addressed as issue <ulink url="https://jira.jboss.org/jira/browse/JBPM-2508">JBPM-2508... </para> + <para> + <emphasis role="bold">Known console limitation</emphasis>: + Currently, the timeout of the console is too tight for the reporting + to initialize on slower machines. So the first time when you access + the reporting the request will timeout and the console crashes. + Logging out and login again works around this problem. It's being + addressed as issue + <ulink url="https://jira.jboss.org/jira/browse/JBPM-2508">JBPM-2508... + </para> </section> <section id="installscripts"> <title>Install scripts</title> <para>The jBPM download contains an <literal>install</literal> directory with an ant <link>build.xml</link> file in it. You can use that to - install jBPM into your application environment. + install jBPM into your application environment. </para> <para>It's best to stick to the installations and jBPM configuration files @@ -106,18 +121,129 @@ directly, is possible, but not supported. </para> - <para>To invoke the install script, open a command line and go to the + <para> + To invoke the install script, open a command line and go to the <literal>${jbpm.home}/install</literal> directory. With <literal>ant -p</literal> you can - find out what each of these scripts can do. + find out what each of these scripts can do. The scripts are parametrized with default values + to get going quickly. The following list gives an overview of the available scripts: + </para> + <para> + <itemizedlist> + <listitem> + <literal>demo.setup.jboss</literal>: installs jboss, installs jbpm into jboss, + starts jboss, creates the jBPM DB schema, deploys examples, loads example identities, + installs and starts eclipse + </listitem> + <listitem> + <literal>demo.setup.tomcat</literal>: installs tomcat, installs jbpm into tomcat, + starts tomcat, creates the jBPM DB schema, deploys examples, loads example identities, + installs and starts eclipse + </listitem> + <listitem> + <literal>clean.cfg.dir</literal>: Deletes the <literal>${jbpm.home}/install/generated/cfg</literal> folder. + </listitem> + <listitem> + <literal>create.cfg</literal>: Creates a configuration in + <literal>${jbpm.home}/install/generated/cfg</literal> based on the current parameters. + </listitem> + <listitem> + <literal>create.jbpm.schema</literal>: creates the jbpm tables in the database + </listitem> + <listitem> + <literal>create.user.webapp</literal>: Generates a basic webapp in + <literal>${jbpm.home}/install/generated/user-webapp</literal> + </listitem> + <listitem> + <literal>delete.jboss</literal>: Deletes the JBoss installation + </listitem> + <listitem> + <literal>delete.tomcat</literal>: Deletes the Tomcat installation + </listitem> + <listitem> + <literal>demo.teardown.jboss</literal>: Drops the jbpm db schema and stops jboss + </listitem> + <listitem> + <literal>demo.teardown.tomcat</literal>: Stops tomcat and then the hsqldb server (if needed) + </listitem> + <listitem> + <literal>drop.jbpm.schema</literal>: Drops the jbpm tables from the database + </listitem> + <listitem> + <literal>get.eclipse</literal>: Downloads eclipse if it is not available + </listitem> + <listitem> + <literal>get.jboss</literal>: Downloads a JBoss AS which was tested against the current jBPM version if it is not available + </listitem> + <listitem> + <literal>get.tomcat</literal>: Downloads tomcat which was tested against the current jBPM version if it is not available + </listitem> + <listitem> + <literal>hsqldb.databasemanager</literal>: Starts the hsqldb database manager + </listitem> + <listitem> + <literal>install.eclipse</literal>: Unzips eclipse, downloads eclipse if it is not available + </listitem> + <listitem> + <literal>install.jboss</literal>: Downloads JBoss if its not available and then unzips it + </listitem> + <listitem> + <literal>install.jbpm.into.jboss</literal>: Installs jBPM into JBoss + </listitem> + <listitem> + <literal>install.tomcat</literal>: Downloads tomcat to ${tomcat.distro.dir} if its not available and then unzips tomcat + </listitem> + <listitem> + <literal>install.jbpm.into.tomcat</literal>: Installs jBPM into tomcat + </listitem> + <listitem> + <literal>install.examples.into.tomcat</literal>: Deploys all the example processes + </listitem> + <listitem> + <literal>install.signavio.into.jboss</literal>: Installs signavio into jboss + </listitem> + <listitem> + <literal>install.signavio.into.tomcat</literal>: Installs signavio into tomcat + </listitem> + <listitem> + <literal>load.example.identities</literal>: Loads the example users and groups into the database + </listitem> + <listitem> + <literal>reinstall.jboss</literal>: Deletes the previous jboss installation and re-installs jboss + </listitem> + <listitem> + <literal>reinstall.jboss.and.jbpm</literal>: Deletes the previous jboss installation and re-installs jboss and installs jbpm in it + </listitem> + <listitem> + <literal>reinstall.tomcat</literal>: Deletes the previous tomcat installation and re-installs tomcat + </listitem> + <listitem> + <literal>reinstall.tomcat.and.jbpm</literal>: Deletes the previous tomcat installation and re-installs tomcat and installs jbpm in it + </listitem> + <listitem> + <literal>start.eclipse</literal>: Starts eclipse + </listitem> + <listitem> + <literal>start.jboss</literal>: Starts jboss and waits till jboss is booted, then lets jboss run in the background + </listitem> + <listitem> + <literal>start.tomcat</literal>: Starts Tomcat and waits till it is booted, then lets Tomcat run in the background + </listitem> + <listitem> + <literal>stop.jboss</literal>: signals jboss to stop, but doesn't wait till its finished + </listitem> + <listitem> + <literal>stop.tomcat</literal>: Signals Tomcat to stop, but doesn't wait till its finished + </listitem> + <listitem> + <literal>upgrade.jbpm.schema</literal>: Upgrades the jBPM tables in the database to the current version + </listitem> + </itemizedlist> </para> - <para>The scripts are parametrized with default values. + <para>To specify your jdbc properties that are used in the scripts above (eg.DB schema generation), + the easiest is to update the appropriate properties file in directory <literal>${jbpm.home}/install/jdbc</literal>. + The appropriate properties file will be loaded by the scripts that are DB related. </para> - <para>To specify your jdbc properties that are used in the DB schema generation, direct DB access like - deployment and for the JBoss datasource creation, the easiest is to update the appropriate - properties file in directory <literal>${jbpm.home}/install/jdbc</literal>. The appropriate properties - file will be loaded by the scripts that are DB related. - </para> - <para>Also following properties you might want to customize:</para> + <para>Also following properties are customizeable</para> <itemizedlist> <listitem><literal>database</literal> : Default value is <literal>hsqldb</literal>. Alternative values are <literal>mysql</literal>, <literal>oracle</literal> and <literal>postgresql</literal></listitem> @@ -152,7 +278,7 @@ to customize the path to your JBoss installation. </para> <para>In JBoss, the <literal>ProcessEngine</literal> can be obtained from JNDI - with <literal>new InitialContext().lookup(&quot;java:/ProcessEngine&quot;)</literal> + with <literal>new InitialContext().lookup(&quot;java:/ProcessEngine&quot;)</literal>. The same ProcessEngine can be obtained with <literal>Configuration.getProcessEngine()</literal> </para> </section> @@ -170,10 +296,6 @@ <literal>install.signavio.into.tomcat</literal> will install the Signavio web based process editor into JBoss or Tomcat respectively. </para> - <para>The signavio webapp is not yet part of the default installation scripts - as it depends on JDK 6. - </para> - <para>After the application started, </para> </section> <section id="userwebapp"> @@ -205,7 +327,7 @@ creating tables and constraints, the mentioned target will initialize table <literal>JBPM4_PROPERTY</literal> with the current engine version (key <literal>db.version</literal>) and the ID generator base value - (key <literal>next.dbid</literal>.</para> + (key <literal>next.dbid</literal>).</para> <para>To drop the schema, simply run target <literal>drop.jbpm.schema</literal>. Be aware that this operation will destroy any data present in the jBPM tables.</para>