Author: scottbw
Date: Fri Nov 27 15:09:13 2009
New Revision: 884892
URL: http://svn.apache.org/viewvc?rev=884892&view=rev
Log:
Updated README
Modified:
incubator/wookie/trunk/readme.txt
Modified: incubator/wookie/trunk/readme.txt
URL:
http://svn.apache.org/viewvc/incubator/wookie/trunk/readme.txt?rev=884892&r1=884891&r2=884892&view=diff
==============================================================================
--- incubator/wookie/trunk/readme.txt (original)
+++ incubator/wookie/trunk/readme.txt Fri Nov 27 15:09:13 2009
@@ -9,38 +9,50 @@
IMPORTANT LEGAL NOTICE
======================
-Apache Wookie (Incubating) depends on several libraries that are licenced
under open source licences that are incompatible with
+Apache Wookie (Incubating) depends on several libraries that are licensed
under open source licences that are incompatible with
the Apache License. When you first build the project these will be downloaded
automatically by the build system.
Configuration
=============
-There are some configuration options in build.properties, these are documented
within the file itself.
+There are some configuration options in build.properties, these are documented
within the file itself. There is also additional
+documentation at
http://incubator.apache.org/wookie/wookie-server-administrators-guide.html
-Building
-========
+Downloading & Building Wookie
+=============================
You will need to download and install Apache Ant in order to build from
source. See http://ant.apace.org
-Once installed run the following commands:
+Wookie is designed to be downloaded using subversion; to checkout the latest
code:
+
+svn co https://svn.apache.org/repos/asf/incubator/wookie/trunk
+
+This will downloaded the latest source code to your current folder.
+
+You then need to enter:
cd PROJECT_HOME_DIRECTORY
ant
-The first time you run this command all dependencies will be downloaded so you
must be online and it will take some time.
-Subsequent builds will be much faster.
+The first time you run this command all dependencies will be downloaded so you
must be online and
+it will take some time. Subsequent builds will be much faster.
-Running
-=======
+You can run Wookie in a number of different configurations, as described in
the following sections.
-The following will compile any changed java files and run the webserver in
demo mode, complete with an embedded database.
-The database will be automatically updated at construction - do not use this
approach in production.
+Running Wookie in "standalone" mode
+===================================
+The quickest way to run Wookie is in "standalone" mode; in this mode Wookie
uses a local database
+and embedded server. This is a good way to experiment with Wookie in
development.
+
+To run Wookie in standalone mode:
-cd PROJECT_HOME_DIRECTORY
ant run
-http://localhost:8080/wookie
-To access the administration menu (http://localhost:8080/wookie/admin) use the
username 'java' and password 'java'.
+The first command will download any required libraries for Wookie. The second
will start a server
+running on port 8080. To access it, go to http://localhost:8080/wookie
+
+To access the administration menu (http://localhost:8080/wookie/admin) use the
username 'java' and
+ password 'java'.
If you want to start with a completely clean build then use:
@@ -50,16 +62,32 @@
ant clean-db
-Deploying using Tomcat and MySQL
-================================
+Running Wookie in debug mode
+============================
+You can start Wookie in debug mode using JDSPA with the following command:
-The following will compile and run the server in Tomcat with a MySQL database.
The database tables will be set up automatically, however you
-must have previously created a database called "widgetdb" with username "java"
and password "java".
+ant -Djvmargs="-Xdebug
-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n" run
-cd PROJECT_HOME_DIRECTORY
-edit the "build.properties" file, uncommenting "project.using.mysql=true" and
setting "servletEngine.webapp.dir=" to the location of your
-tomcat webapps directory.
-ant clean-build deploy-webapp
+Running Wookie with Tomcat and MySQL
+====================================
+The following will compile and run the server in Tomcat with a MySQL database.
The database tables will be set up automatically, however you must have
previously created a database called "widgetdb" with username "java" and
password "java". (If you want to change the database connection settings, then
you need to alter the scripts/mysql/hibernate.cfg.xml.)
+
+First, you need to edit the "build.properties" file as follows:
+
+uncomment "project.using.mysql=true" and comment out "project.using.derby=true"
+set "servletEngine.webapp.dir=" to the location of your tomcat webapps
directory.
+
+Next you need to setup the MySQL tables by running:
+
+ant clean-db
+
+If you have previously used Wookie in standalone deployment, to ensure the
right scripts are included in the build you need to run:
+
+ant clean-build
+
+Then to build and deploy the webapp, run:
+
+ant deploy-webapp
To access the administration menu (http://localhost:8080/wookie/admin) use the
username 'java' and password 'java'.
@@ -71,10 +99,16 @@
ant clean-db
-Debugging
-=========
+By default Wookie connects to MySQL using Hibernate and the C3P0 connection
pooler.
+
+Once the server is running connect your debugger to port 8000. If "suspend=y"
is used, it will will block, waiting for a debug connection before starting the
server.
-To run the server in debug mode on a specific port use the wookie.jvmargs
property, as follows:
+Running Wookie with other configurations
+========================================
+Other configurations of Wookie can also be run; the main requirements are a
servlet container and a database. The setup information for databases can be
found in the /scripts directory. How these are loaded into configurations is
defined in build.xml; the main requirement is to define connection details in
scripts/database/hibernate.cfg.xml and to define the database setup script in
scripts/database/widgetdb.sql.
-ant -Dwookie.jvmargs="-Xdebug
-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n" run
+The deploy-webapp task can be used to deploy Wookie to any servlet container
application.
+Building and deploying widgets
+==============================
+See http://incubator.apache.org/wookie/building-widgets.html
\ No newline at end of file
