Getting started

Pustefix Homepage

  1. What is Pustefix
  1. Download
  1. Getting started
  1. ToDo
  1. Documentation
  1. Eclipse Plugin

This section describes how to get Pustefix up and running.

  1. Download the pfixcore-skel-*.tar.gz and unpack it.
  2. Place a current version of Tomcat 5.5 (.tar.gz) in the lib/tomcat directory of the newly created pustefix environment.
  3. Create a build.properties with the content: 
      makemode=test
  standalone.tomcat=true
    You might want to change these settings later, but for the beginning they are okay.
  4. Open projects/common/conf/pustefix.xml, look for the property derefserver.signkey, uncomment it and set it to some random value. Make the value really complicated and random, you don't have to remember it or use it anywhere else, it's just a key that is used internally and that must be different for each installation and impossible to guess.
  5. Run ant to run the initial tasks like unpacking pfixcore.
  6. Create a new project: Run ./newproject.sh and follow the instructions.
  7. Type ant to build your project.
  8. Start tomcat: ./startTomcat.sh
  9. Point your browser to !http://YOURPROJECT.HOSTNAME.DOMAIN:8080/
  10. Press Control-C to stop Tomcat.

Example projects

To install the pustefix examples, just unpack the respective download with tar xvzf example.tar.gz into the projects directory and take a short look at the resulting README_EXAMPLES.txt file.

To get started with the examples, please study the de.schlund.pfixcore.util.basicapp. package. If you start with InitNewPfixProject.java (in the package basics) it should be easy to understand the way to go.

Apache configuration

Prerequisites: Make sure your machine is configured as follows

  1. Your host ip must not be 127.0.0.1. (TODO: why, what happens if not.) Verify this by running ping HOSTNAME
  2. Your dns domain is configured properly: hostname -d should yield your host's domain. If not set up propertly, you tomcat configuration (server.xml) contains invalid host names.
  3. Pustefix uses virtual hosts, i.e. a lookup to FOO.HOSTNAME.DOMAIN should resolves to HOSTNAME.DOMAIN no matter what FOO is. Test this by running ping FOO.HORSTNAME To configure this you can add an * entry to your DNS configuration. Alternatively, you can add individual entries for every project (e.g. sample1.HOSTNAME.DOMAIN) to your /etc/hosts.
  4. The pustefix directory has to be world-readable, otherwise, apache cannot serve static resources like pictures or style-sheets. Usually, this is done by running chmod a+rx.

TODO: doesn't belong to getting started - it's an advanced subject.

To run pustefix applications in productions environments, you might want to embed tomcat in an apache web server. This section describes how to do this on Linux machines.

  1. Install Apache 2: Rpm packages are supplied for most Linux distributions.
  2. Install mod_jk: mod_jk is the apache connection module for tomcat. Rpm packages can be found at jpackage.org. Gentoo: emerge mod_jk. Documentation can be found here.
  3. Make sure that mod_ssl is installed: look for a file /usr/lib/httpd/modules/mod_rewrite.so. Without mod_ssl, apache will complain that about the httpd.conf include below. Most distributions include mod_ssl rpm files.
  4. Make sure the rewrite module is installed: look for a file /usr/lib/httpd/modules/mod_rewrite.so
  5. Load mod_jk: Add the following line to your httpd.conf, right before the rewrite module configuration: !LoadModule jk_module modules/mod_jk.so Caution: There have been problems with the order of inclusion of mod_rewrite and mod_jk. It seems that mod_jk needs to be loaded BEFORE mod_rewrite. Other problems that have been experienced are related to a changed regexp syntax between different versions of mod_rewrite. You may have to customize the relevant regexps in the file core/build/create_apacheconf.xsl.
  6. Configure pustefix: Append the following lines to your httpd.conf. Substitute the capitalized fragments to reflect your configuration. 
      # at the end
  NameVirtualHost HOSTNAME.DOMAIN:80
  NameVirtualHost HOSTNAME.DOMAIN:443
  # config for mod_jk
  Include /YOUR_ENVIRONMENT/projects/servletconf/tomcat/jk.conf
  # virtual hosts for tomcat:
  Include /YOUR_ENVIRONMENT/projects/servletconf/tomcat/apache.conf

Modern apache installations often have an httpd.conf.d directory where to put links to config files that should be included automatically. In this case you can link the two files there instead of including them via your http.conf.

Finally restart apache and you're ready to go.