Can't see the forest through the trees ?

Apache Forest : Documentation and Website generating system


As added value to or small business Linux server, we could install MediaWiki, which can be used as a document management / collaboration system, a 'groupware' like environment to create, store and share information, or a content management system for the intranet. However, it is difficult to convert wiki-generated pages into static web pages. If for some reason that is something you want, Appache Forrest may be a better idea.

One application (other than documenting a software development project, which it was originally intended for) is to use Apache Forrest to generate web pages. You can run a private apache web server with forrest to generate pages, then upload them as html pages to that free web space that came with your internet account but where you don't have any control over the webserver itself.

prerequisites

set up a linux server with Apache.

What is Forrest

Apache Forrest is a publishing framework that transforms input from various sources into a unified presentation in one or more output formats. The modular and extensible plugin architecture is based on Apache Cocoon and relevant standards, which separates presentation from content. Forrest can generate static documents, or be used as a dynamic server, or be deployed by its automated facility. Forrest is built on the world's leading XML application framework, Apache Cocoon, which provides advanced users with extremely powerful publishing capabilities.
forrest.apache.org/.

Install Forrest

To install Forrest, you can download de gzip tar archives from forrest.apache.org/, or look for an install package for your Linux distribution of choice. For Debian, Forrest is in the Unstable branche so if you want to install it on a stable or testing system, you may want to look into A mixed Debian system.

Add a "unstable contrib" line to /etc/sources.list, edit /etc/apt/preferences, and run

	apt-get -t unstable install forrest/

You also need Java, so if it is not there, it needs to be installed. To install Java on Debian, you will need to download a Java Runtime Environment as Linux selfextracting file (eg. jre-1_5_0_09-linux-i586.bin). (Sun).
Then, run the following commands :

	apt-get install java-package fakeroot

	# need to run this as non-root and from directory where jre is downloaded to
	# can take a while and produces errors but just wait until the procedure ends
	# the result should be a 

	su kn
	cd /home/kn/javadeb
	fakeroot make-jpkg $(ls *.bin)
	su
 	dpkg -i *.deb

	

forrest expects an environment variable to find where java is located, but this is not created during setup so we add it ourself.

	# set up the environment
	# 	and create a startup script to reproduce it after a reboot

	(echo "#!/bin/sh"
	echo "echo setting JAVA_HOME environment variable"
	echo "export JAVA_HOME=/usr" ) > /etc/init.d/java
	chmod 755 /etc/init.d/java
	update-rc.d java start 60  2 3 4 5 .
	/etc/init.d/java
	

Run, Forrest, run ...

Forrest will generate "projects" that will later be published as web sites. You'll need a dedicated space for your projects, eg. a subdirectory in your home folder, or a directory in /srv. Your web server document root is not involved yet. Start with a dedicated directory per project and cd in to it before using forrest, as forrest will generate its projects in 'current directory'.

To create a project :

		cd /srv/forrest
		mkdir prj_test01
		cd proj_test01

		forrest seed
		forrest
	

'forrest seed' creates a number of default project files and templates which you can now start building your project (or website) on. The second 'forrest' creates a static site based on the files in the working directory.

The static site is generated at FORREST_HOME/[project_directory]/build/suite - in this example that is
/srv/forrest/prj_test01/build/site
To view the site in a (remote) browser, you can either

If all of this went as planned, you have now a working Apache Forrest configuration, and we can start working on customizing it. (TODO, still working on that)

What have we got ?

.../forrest/project-directory

forrest.properties
used to set properties for this project's website, i.e. how will forrest 'build' this website ? covers

.../forrest/project-directory/src/documentation

the src directory contains the content for this site.

skinconf.xml
This file customizes Forrest for your project. In it, you tell forrest the project name, logo, copyright info, etc
sitemap.xml
Optional : This sitemap overrides the default one bundled with Forrest.
content (directory)
Here you will create content for your site. The main file here is /src/documentation/content/xdocs/site.xml where you will define content and parts of the navigation (which pages will appear behind what tab, etc).
resources (directory)
Here you will have directories for images etc.

.../forrest/project-directory/build/

contains 'site' and 'tmp' directories

.../forrest/project-directory/build/site/

This directory contains the static pages (html, css, images, ...) that together constidute your website. As Forrest is a content / document management system, there should be no need to modify these files manually : they should be generated by the build process, using the forrest.properties you've set for this project and the content in .../forrest/project-directory/src/. However, it is usefull to have a look at them to see how the forrest properties and content translate to web pages.

Contents of .../build/site/

index.html
the project's home page.
.html, .pdf, ...
other pages that constitute the contents of your site
images directory
images that are not part of a specific skin and will appear on any site (project name, "build with Forrest" button, ...
skin directory
parent directory for css (stylesheets), images and scripts directories : the components for your site's layout and look-and-feel.

Overview


kdunix:/srv/forrest/prj_test01# find . -maxdepth 4 -type d
	.
	./src

	./src/documentation
	./src/documentation/resources
	./src/documentation/content

	./build

	./build/site
	./build/site/images

	./build/site/skin
	./build/site/skin/images
	./build/site/skin/scripts
	./build/site/skin/css
	

Creating a web site

So, let's have a look at how to create a website with Apache Forrest. We will want a rather basic, business-like website with a consistent look and feel, but not one of the prefab styles that come with Forrest. Too many websites already look like so many others that used the same technology : wiki's, phpBB-driven forums, out-of-the-box FrontPage templates ...

A documentation system such as Forrest should allow us to concentrate on content, and add layout and presentation automatically. Say we want to develop a web site for "Useless Publications Unlimited" , a publishing company that stopped publishing printing matter but now focuses on publishing articles of general interest on the web. We'd be interested in a customized skin (our 'corporate image' house style), common headers and footers for each page, with some static and variable data, such as "where am I" navigation ("bread crumbs"), page creation and latest update date, author, the company's logo, automatically updated table of contents, a number of subsections to group articles with a common theme or subject, posibly with a slightly modified appearance for each subsection, and so on.


References


Koen Noens
October 2006

Inspired by an article in iX, magazine for professional IT, juli/august 2006 Dutch edition.