Our Contract

+Searching +

Our Contract

Advanced Topics

Upgrading

SubProjects

+ForrestBar +

+Forrestbot +

+Forrestbot We= bapp +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

Older Docs

+Libre +

+ This is documentation for past release v0.6 + (More ...)

+ +

+ + +

+ Font size:=20 + = =20 + + +

Our Contract

This document describes, in a very techy bullet-st= yle way, how + to use Forrest.

+ This is documentation for past release v0.6 + (More ...)

=20 + =20 +

Note

+ This document describes the formal contract between the + Forrest distribution code, hereafter referred as=20 + "Forrest", and + the Project (team) that is using it for generating + its documentation and web-site, hereafter referred to as "TheProjec= t". +

+ =20 +

Note

+ Some terminology will assist: {docroot} is the location + inside TheProject's file hierarchy where all documentation related + resources are stored. Usually {docroot} equals to + {projecthome}/src/documentation + =20 +

=20 + + =20 + +

Forrest will:

Provide infrastructure ...

Provide document type definitions (DTDs), skins, default sitemaps, + Cocoon pipelines. +
Provide a willing team of supporting developers at the forrest-dev + mail list. +
Use Cocoon to generate the HTML and PDF documentation for + TheProject.

+ + =20 + +

TheProject must:

Provide content and configuration ...

Provide XML content in {docroot}/content/xdoc= s + according to the Forrest DTDs or one of the other input formats. +
Provide navigation metadata using the configuration files + site.xml and tabs.xml + =20 +
Provide the skin configuation file in + {projecthome}/skinconf.xml + =20 +

=20 + + =20 + +

TheProject can:

Add extra abilities ...

Provide its own skin in + {docroot}/skins/{your-skin-name}= (Check the current + Forrest skins and the related pipelines to see what they are doi= ng. + Bear in mind that the provided skins are able to be configured a= nd + may already meet your needs.)
Provide own DTDs to handle other specialised document types in + {docroot}/resources/schema/dtd=20 + =20 +
- and extra stylesheets to convert own grammar to the + intermediate 'document' structure.
- and declare those extra DTDs in + {docroot}/resources/schema/catalog.= xcat +
+ =20 +
Provide its own overwriting versions of sitemaps + ({docroot}/sitemap.xmap and othe= r *.xmap files) + ... (be sure you know what you are doing since you are then leav= ing + the area where other Forresters can help you out. +

=20 + =20 +

+ +

+ + + Propchange: forrest/site/0.6/docs/forrest-contract.html ---------------------------------------------------------------------------= --- svn:eol-style =3D native Added: forrest/site/0.6/docs/forrest-contract.pdf URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrest-contract.p= df?view=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Binary file - no diff available. Propchange: forrest/site/0.6/docs/forrest-contract.pdf ---------------------------------------------------------------------------= --- svn:mime-type =3D application/pdf Added: forrest/site/0.6/docs/forrestbar.html URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbar.html?vi= ew=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- forrest/site/0.6/docs/forrestbar.html (added) +++ forrest/site/0.6/docs/forrestbar.html Mon Apr 11 08:11:56 2005 @@ -0,0 +1,320 @@ + + + + + + + + +The ForrestBar (v0.6) + + + + + + + + + +

+ +

+apache > forrest +

+ + +

+ +

+Core | <= a class=3D"base-selected" href=3D"../docs/forrestbot.html">ForrestBot |= ForrestBar +

+ + +

+ +

+ =20 + +

+ + +

Documentation

+Index +

+Searching +

+Our Contract +

Advanced Topics

Upgrading

SubProjects

ForrestBar

+Forrestbot +

+Forrestbot We= bapp +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

Older Docs

+Libre +

+ This is documentation for past release v0.6 + (More ...)

+ +

+ + +

+ Font size:=20 + = =20 + + +

The ForrestBar

+ This is documentation for past release v0.6 + (More ...)

+What's the Forrestbar? +
+Installing the Forrestbar +

+=20 + +

What's the Forrestbar?

The Forrestbar is a toolbar made for Mozilla=20 + (and Firefox compatible) + that eases the navigation of Apache=20 + projects and resources, and to the local Forrest running on your = machine.

+ =20 + +

Installing the Forrestbar

Note

Forrestbar does not currently work with Firefox 0.9= +

To install the latest nightly version brought to you by=20 + Gump in <= a class=3D"external" href=3D"http://www.mozilla.org/">Mozilla + or Firefox, just=20 + + install it or download it + and drop it on a mozilla window.

To get the latest and greatest version run the forrestbar target of the= Forrest build.

+ =20 +

+ +

+ + + Propchange: forrest/site/0.6/docs/forrestbar.html ---------------------------------------------------------------------------= --- svn:eol-style =3D native Added: forrest/site/0.6/docs/forrestbar.pdf URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbar.pdf?vie= w=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Binary file - no diff available. Propchange: forrest/site/0.6/docs/forrestbar.pdf ---------------------------------------------------------------------------= --- svn:mime-type =3D application/pdf Added: forrest/site/0.6/docs/forrestbar.xpi URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbar.xpi?vie= w=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Binary file - no diff available. Propchange: forrest/site/0.6/docs/forrestbar.xpi ---------------------------------------------------------------------------= --- svn:mime-type =3D application/octet-stream Added: forrest/site/0.6/docs/forrestbot-web-interface.html URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbot-web-int= erface.html?view=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- forrest/site/0.6/docs/forrestbot-web-interface.html (added) +++ forrest/site/0.6/docs/forrestbot-web-interface.html Mon Apr 11 08:11:56= 2005 @@ -0,0 +1,492 @@ + + + + + + + + +Forrestbot Web Interface (v0.6) + + + + + + + + + +

+ +

+apache > forrest +

+ + +

+ +

+Core | <= a class=3D"base-selected" href=3D"../docs/forrestbot.html">ForrestBot |= ForrestBar +

+ + +

+ +

+ =20 + +

+ + +

Documentation

+Index +

+Searching +

+Our Contract +

Advanced Topics

Upgrading

SubProjects

+ForrestBar +

+Forrestbot +

Forrestbot Webapp

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

Older Docs

+Libre +

+ This is documentation for past release v0.6 + (More ...)

+ +

+ + +

+ Font size:=20 + = =20 + + +

Forrestbot Web Interface

+ This is documentation for past release v0.6 + (More ...)

+Build +
+Requirements +
+Installation +
+FAQ +
- +The b= uild and/or deploy commands don't seem to work +
- +Can I do anything with this besides just running the + forrestbot? +
+
+TODO Wishlist +

+ =20 +

This webapp implements a website staging application for sites built wi= th + Apache Forrest. The webapp hosts HTML for a number of managed websites= . The + user can regenerate these sites at will. Once the user is satisfied wi= th the + site, they may 'deploy' the site, making it live.

+ + =20 + +

Build

To build the webapp from source, you need Apache Maven installed. From a + command prompt, go to the forrest/src/forre= stbot/webapp + directory and execute "maven war". +

+ + =20 + +

Requirements

Forrest
A servlet container such as Apache Tomcat +
Directories for:

forrestbot buildfiles
source and working files
log files
built websites (this is not their deployed location)

A webserver to view the sites in the build directory

The server does not need local access to the sites' source nor final + deployed location. The buildfiles configure the transfer of those + files.

+ + =20 + +

Installation

Note

Most of this configuration is related to the OpenSymphony O= SUser + authentication layer.

Extract the war to an empty directory
Modify welcome.local.html
Modify WEB-INF/classes/osuser.xml if you want to use an + authenticator other than XML files
Modify projects.xml, groups.xml, and users.xml (all in + WEB-INF/classes) according to your needs
Optionally modify logging via WEB-INF/classes/log4j.properties
Modify WEB-INF/classes/settings.properties according to the server's + specific setup
Deploy the webapp in Tomcat or some other servlet container (you may + want to repackage the war file)
Make sure tomcat has permissions to write in forrestbot's build, + work, and log directories.

Optional: set up "cron jobs" to execute forrestbot. This is completely + independant of the forrestbot web interface, but is often useful. A + suggested practice is to build the sites regularly and deploy them as + desired through the web interface.

+ + =20 + +

FAQ

+ +

The build and/or deploy commands don't seem to = work

Warning

The only environment variable available is FORREST_= HOME, which + is set by forrest-home in the settings.properties file. Use a wrap= per + script (see below) if you need other environment variables.

Currently forrestbot only logs the forrest part of it's execution, + not the whole thing. And the web interface starts a forrestbot pro= cess + and doesn't watch it's progress directly.

Set debug-exec=3Dtrue in settings.properties and make sure + log4j.properties logs at the DEBUG level. This will log all the th= read + output.

Then look at the debugging output for the command executed and the + working directory used. Log into the server as the use the Tomcat = server + uses and cd to the working directory and then execute the command.= This + will fairly accurately simulate what the web interface does.

+ +

Can I do anything with this besides just runnin= g the + forrestbot?

Sure. Create a wrapper script and specify it as forrest-exec in + settings.properties. Here's an example:

#!/bin/bash
+
+# get env vars
+=2E /home/user/.profile
+
+# group writable for easier sharing of files with others who run forrestbot
+umask g+w
+
+# you can preprocess something here
+xmlfile=3D$2
+if [ "${xmlfile##*.}" =3D "xml" ]                # everything after last .
+then
+    target=3D$3
+    if [ "$target" !=3D "deploy" ]                # don't run preprocess t=
ask on a deploy
+    then
+        projectTarget=3D${xmlfile%.*}               # everything before la=
st .
+        # do something special for $projectTarget here
+    fi
+else
+        echo "Syntax: forrest_wrapper.sh -f myapp.xml [build|deploy|...]"
+        exit
+fi
+
+# run forrest(bot) with all the parameters
+forrest $*
+
+# you can postprocess something here

+ + =20 + +

TODO Wishlist

seperate authorization of 'build' and 'deploy'
log everything, not just the build
view old log files
ability to reload all config files on the fly
put date at top of viewlog_body page

+ =20 +

+ +

+ + + Propchange: forrest/site/0.6/docs/forrestbot-web-interface.html ---------------------------------------------------------------------------= --- svn:eol-style =3D native Added: forrest/site/0.6/docs/forrestbot-web-interface.pdf URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbot-web-int= erface.pdf?view=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D Binary file - no diff available. Propchange: forrest/site/0.6/docs/forrestbot-web-interface.pdf ---------------------------------------------------------------------------= --- svn:mime-type =3D application/pdf Added: forrest/site/0.6/docs/forrestbot.html URL: http://svn.apache.org/viewcvs/forrest/site/0.6/docs/forrestbot.html?vi= ew=3Dauto&rev=3D160902 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D --- forrest/site/0.6/docs/forrestbot.html (added) +++ forrest/site/0.6/docs/forrestbot.html Mon Apr 11 08:11:56 2005 @@ -0,0 +1,1210 @@ + + + + + + + + +Forrestbot (v0.6) + + + + + + + + + +

+ +

+apache > forrest +

+ + +

+ +

+Core | <= a class=3D"base-selected" href=3D"../docs/forrestbot.html">ForrestBot |= ForrestBar +

+ + +

+ +

+ =20 + +

+ + +

Documentation

+Index +

+Searching +

+Our Contract +

Advanced Topics

Upgrading

SubProjects

+ForrestBar +

Forrestbot

+Forrestbot We= bapp +

Reference docs

DTD documentation

+Overview +

+howto-v20 +

+faq-v20 +

+howto-v13 +

+faq-v13 +

Doc samples

Older Docs

+Libre +

+ This is documentation for past release v0.6 + (More ...)

+ +

+ + +