Downloading Wookie
Wookie is designed to be downloaded using subversion; to checkout the latest code:
svn co http://svn.apache.org/repos/asf/incubator/wookie/trunk
If you are a committer you should use https:// rather than http://
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.
You can run Wookie in a number of different configurations, as described in the following sections.
Configuring your IDE
Wookie use Apache Ivy to resolve dependencies, you will therefore need the IvyDE plugin available at http://ant.apache.org/ivy/ivyde/index.html.
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:
ant clean-db run
The first time you run wookie (or compile it) any required libraries will be downloaded, this can take some time and requires a network connection.
The "clean-db" target ensures that your development environment starts in a consistent state. However, any modifications you have made to the database during previous runs will be lost.
To run the development server without cleaning the database you need to set initDB=false
. See the next section for more details.
Once the server is running 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:
ant clean-build clean-db run
Running options
To set run mode options you can either add properties to the local.build.properties
file or you can pass properties in via the command line using -Drun.args="<property_name>=<property_value> <property_name>=<property_value>"
. For example:
-Drun.args="port=8080 initDB=false"
Available properties are:
Property |
Values |
Description |
Default |
---|---|---|---|
initDB |
True or False |
Initialise the DB to a default configuration |
True |
port |
Integer |
Set the port on which the server is to run |
8888 |
Running Wookie in debug mode
You can start Wookie in debug mode using JDSPA with the following command:
ant -Djvmargs="-Xdebug -Xrunjdwp:transport=dt_socket,address=8001,server=y,suspend=n" clean-db run
Once Wookie is running in debug mode you need to connect to it using your debugger.
Debugging with Eclipse
To connect Eclipse to Wookie running in debug mode on your local machine you would:
{{Run -> Debug Configurations... }}
Select "Remote Java Application"
Click "New Launch Configuration"
Set as follows:
Name: Wookie Debug (Localhost)
Project: Click "Browse" and select your Wookie project
PORT: 8001
Now click the "Debug"
button (note you must be running Wookie in debug mode, see above, first).
You can now set breakpoints etc. as if you were running from within Eclipse.
Once you have set up this "debug configuration" you can quickly access it from your debug menu.
For more on remote debugging with Eclipse see http://www.eclipsezone.com/eclipse/forums/t53459.html
Note, you can set up a run configuration to be able to run Wookie from the UI of Eclipse, but I'll leave that for you to work out as I use the command line.
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.)
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.
- set "widget.deploy.dir=" to the "deploy" folder of the deployed application, e.g. "tomcat/webapps/wookie/deploy"
- set "servletEngine.container.lib.dir" and "servletEngine.context.conf.dir" as described in the comments in build.properties
- complete the database connection details for your database, or simply uncomment to use the default MySQL database setup described above.
Create a user with the role "widgetadmin" in your tomcat installation. For example, add the following to tomcat-users.xml:
<role rolename="widgetadmin"/>
<user username="java" password="java" roles="widgetadmin"/>
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
You can then start Tomcat as usual.
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:
ant clean-build deploy-webapp
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.
Running Wookie with a security manager
If you are running Wookie with a security manager you will have to grant some permissions to get Wookie running properly. Otherwise you are likely to run into this of a similar error:
SEVERE: Exception sending context initialized event to listener instance of class org.apache.wookie.server.ContextListener java.security.AccessControlException: access denied (java.util.PropertyPermission user.dir read) at ...
If you can't turn off the security manager but don't really care about it, you can consider to replace to contents of the policy file (in Tomcat this is typically $TOMCAT_HOME/conf/catalina.policy
, Ubuntu users will find the policy files in /etc/tomcat6/policy.d/
) with the grant all statement:
grant { permission java.security.AllPermission; };
This is not a recommended way of working for a production environment, because it effectively means turning off security alltogether.
Another option is to properly configure the security policy file. Below is a list of permissions that Wookie needs. Most of these are for Hibernate that needs to generate 'enhanced' classes at runtime.
// fixes access denied (java.util.PropertyPermission user.dir read) grant { permission java.util.PropertyPermission "*", "read,write"; }; // fixes access denied (java.io.FilePermission TOMCAT_HOME\bin\local.widgetserver.properties read) grant { permission java.io.FilePermission "<<ALL FILES>>", "read, write"; }; // fixes access denied (java.net.SocketPermission localhost resolve) grant { permission java.net.SocketPermission "*", "resolve,connect"; }; // fixes access denied (java.lang.RuntimePermission accessClassInPackage.org.apache.catalina) // fixes access denied (java.lang.RuntimePermission accessDeclaredMembers) // fixes access denied (java.lang.RuntimePermission getProtectionDomain) grant { permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina"; permission java.lang.RuntimePermission "accessDeclaredMembers"; permission java.lang.RuntimePermission "getProtectionDomain"; }; // fixes access denied (java.lang.reflect.ReflectPermission suppressAccessChecks) grant { permission java.lang.reflect.ReflectPermission "suppressAccessChecks"; };
Note that some of these fixes are still not very strict, which means that if you
are really concerned to limit permissions as much as possible, you need to define
stricter rules, but it's a start and should get your Wookie instance up-and-running.
For more information how to do this in Tomcat, see the Security Manager HOW-TO
Running Wookie with other configurations
Other configurations of Wookie can also be run; the main requirements are a servlet container and a database.
Database connections can be set up using either JPA (Java Persistence API) or JCR; the configuration details are set in build.properties. Additional configuration for advanced use can be found in org.apache.wookie.beans.jpa/peristence.properties. The database schema and mappings is located in etc/ddl-schema.
The deploy-webapp task can be used to deploy Wookie to any servlet container application.