root/trunk/pfixcore/INSTALL

This file describes how to get the package up and running.

Prerequisites:

        * A unixoid OS.  Yes, Java should be platform independent.
          Unfortunately portions of the build environment and code
          require a unix-like shell. Running Pustefix on Windows might
          work using Cygwin, but we haven not tried yet. If you succeed
          in running Pustefix on Windows, we would like to hear.

        * A Java installation.  Version 1.5 is required and version 1.6
          is recommended. The environment variable JAVA_HOME must be 
          set to the root directory of your java installation.
          
        * Apache Ant, the Java-based build tool in version 1.7.0 or higher.
          If you have really large projects consider increasing the memory
          for the java vm ant runs in: To do this set the ANT_OPTS
          environment variable to something like "-mx200m". This variable
          is evaluated within the ant start script contained in the ant
          distribution.

        * If you want to use Pustefix with the Apache HTTP daemon, either
          mod_proxy_ajp or mod_jk have to be installed and loaded.
          However, you can simply run Pustefix without Apache by setting
          the standalone.tomcat property to true when running "ant".
          Tomcat will listen for incoming HTTP connections on port 8080 
          and for HTTPS connections on port 8443.
          
          If you are using Apache, name-based virtual servers have to be
          enabled for the default address of your machine. 
          
          Note that there have been problems with the order of
          inclusion of mod_rewrite and mod_jk in the Apache configuration
          file. It seems that mod_jk needs to be loaded
          BEFORE mod_rewrite. If you experience problems, try changing
          the order of these two modules.  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.
          
        * You should have a "* entry" for your machine in DNS (This means that 
          a lookup to NAME.HOSTNAME.DOMAIN should resolve to HOSTNAME.DOMAIN no
          matter what NAME is). If you don't have DNS configured like this you can 
          still supply the names (e.g. "cms.HOSTNAME.DOMAIN" or 
          "sample1.HOSTNAME.DOMAIN") via your /etc/hosts file.
          
        * NOTE: you don't need a external installation of Tomcat,
          everything you need is contained in this package.  We suggest
          that even if you have your own Tomcat setup already,
          start by using the supplied versions, and, if all goes
          well, you can try to move the configuration into your own
          installation.

        * NOTE2: you don't need any additional jar files or classes besides
          what is supplied with your java installation and this package.
 
1)  Type "ant" to generate all neccesary files and compile all classes.

2)  You may want to type "ant generate" for pre-processing all the templates
    up-front. This speeds up the first hit of a page in the sample
    applications as the page doesn't need to be build from scratch then.

3)  Put something  like the following

        NameVirtualHost HOSTNAME.DOMAIN:80
        # uncomment if you want to use SSL
        # NameVirtualHost HOSTNAME.DOMAIN:443

        # config for mod_jk
        Include <your path to this directory>/projects/servletconf/tomcat/jk.conf

        # virtual hosts:
        Include <your path to this directory>/projects/servletconf/tomcat/apache.conf

    into your Apache configuration. Don't forget to restart apache. 
    Modern apache installations often have a 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

4)  Start Tomcat with the following command:

        ./startTomcat.sh

    Note: For stopping Tomcat, just press Control-C to interrupt the script.
        
5)  To see if everything works, you can try to open the editor
    application. Point your browser to
        
        http://cms.HOSTNAME.DOMAIN 

6)  You will find some basic applications in the example.tar.gz.
    Just unpack the file with "tar xvzf example.tar.gz" in your skel/projects 
    directory and take a short look to the README_EXAMPLES.txt included in the 
    tar afterwards.
    
7)      Creating your own pustefix project is really simple. If you're in 
        the skel dir just type in "./newproject.sh" 
        and follow the command-line
        instructions. 
        Afterwards run ant, restart apache, restart tomcat and type in
                http://myprojectname.HOSTNAME.DOMAIN
                
        To see how it works you should take a short look in 
        de.schlund.pfixcore.util.basicapp. 
        If you start with InitNewPfixProject.java (in the package basics) it should 
        be easy to understand the way to go
    
    Have Fun.


FINAL NOTE:

You can now start building your own applications. Some tutorials as well as the
reference documentation can be found on http://www.pustefix-framework.org/.