[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]


webbapps-common developer documentation
Chapter 2 - Quick HowTo for webapps-common and Web Applications


BIG DISCLAIMER: this is a work in progress. standard it-breaks-you-keep-the-pieces disclaimer here. I'm not even promising i won't even change the API at this point.


2.1 Quick and dirty: what to do

Okay, so this all sounds great... but how do I use it in my package, you ask? For the simplest of installations, you basically need to do three things:


2.1.1 Providing template web-server configuration

during configuration, webapps-common will look for a template webserver file in the location /usr/share/webapps-common/install/PACKAGE/httpd/apache_template.

TODO: the location is ugly, and the documentation is apache-specific.

The configuration file should contain everything needed for the application to properly function. Additionally, it should contain macros to be expanded by webapps-common that will make it customizable based on how the local admin has chosen to install the application. here is an example of such configuration:

     			# this is a sample template-based configuration file for apache.
     			# this file will be included as-is, with the exception that
     			# certain substitutions will occur with the result
     
     			# this macro expands to either a DocumentRoot or an Alias 
     			# directive, depending on whether this app is configured to
     			# run as a top level (i.e. www.foobar.com) or a subdirectory
     			# based configuration respectively.  
     			_WC_DOCROOT_DIRECTIVE_
     
     			# it is important to use Location instead of Directory
     			# for the webapps-common based config if you have an application
     			# that supports multiple instances
     			<Location _WC_WEBSITE_SUBDIRECTORY_>
     				# other settings here that relate to your application
     				# for example, if your app ships with its own php libraries:
     				php_value include_path ".:/usr/share/foo/lib"
     			</Directory>

In the above example, the most important part is the _WC_DOCROOT_DIRECTIVE_, which will conditionally expand to either an Alias or DocumentRoot directive depending on how the application is configured.

For a full list of substitution variables, see Configuration template substitution variables., Section 5.2.


2.1.2 Putting in maintainer script hooks

Next, you will need to insert the webapps-common maintainer script hooks into your package's maintainer scripts, which consists of sourcing a particular shell script library, possibly setting a few variables to influence the behaviour of webapps-common (see Maintainer script hook variables, Section 5.1 for a full list), and then calling the wc_go function with the package name followed by the arguments passed to the maintainer script. The following example illustrates how this would be done in the config maintainance script.

     			if [ -f "/usr/share/debconf/confmodule" ]; then
     				. /usr/share/debconf/confmodule
     			fi
     			if [ -f "/usr/share/webapps-common/dpkg/config" ]; then
     				. /usr/share/webapps-common/dpkg/config
     				wc_go PACKAGE $@
     			fi

you must place these hooks into your config, postinst, prerm, and postrm scripts (or in otherwords in every maintainer script except the preinst).


2.2 Working Examples

If you would like to see working examples of packages currently using webapps-common, grab the latest webapps-common source from alioth, and look in the examples subdirectory. This directory contains debian source packages that generates packages implementing each of the above installation methods. Simply run the included buildpackages.sh script to generate them.


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ next ]


webbapps-common developer documentation

$Revision: 133 $

Sean Finney