[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.sgml,1.14,1.15
seanius at haydn.debian.org
seanius@haydn.debian.org
Wed Jul 6 03:40:03 UTC 2005
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv11389
Modified Files:
Webapps-Policy-Manual-DRAFT.sgml
Log Message:
made it to the bottom :)
Index: Webapps-Policy-Manual-DRAFT.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/Webapps-Policy-Manual-DRAFT.sgml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- Webapps-Policy-Manual-DRAFT.sgml 6 Jul 2005 01:29:37 -0000 1.14
+++ Webapps-Policy-Manual-DRAFT.sgml 6 Jul 2005 03:39:18 -0000 1.15
@@ -145,6 +145,27 @@
<p>The subset of include files intended
for site wide use by multiple
applications.
+ <tag><item>
+ <p><strong>Document root or web root</strong>
+ <p>The base directory underneath
+ which web content is accessed.
+ This sometimes will refer to
+ the "global" document root
+ (parent directory for entire
+ web site), and sometimes
+ refer to an "application"
+ document root, which is the
+ root directory specific to
+ an application.
+ <tag><item>
+ <p><strong><var>PACKAGE</var></strong>
+ <p>generally speaking, the name of the
+ package containing the web application.
+ however, it can also be expanded to include
+ names of other packages (or virtual packages)
+ generated by the same source package, or
+ other commonly acceptable variations on said
+ package names.
</taglist>
<chapt id="issues">Common issues and recommended solutions
<sect id="issues-fhs">Web applications and the FHS
@@ -340,27 +361,48 @@
if such files are intended to be executed via
the web, they must not exist in a location
where they can be directly retrieved.
- <chapt id="libs">Libraries for web applications
- <sect id="libs-phplibs">PHP libraries issues
- <p><em> FIXME: Should also discuss "PHP libraries security issues".</em>
+
+ <chapt id="libs">Includable files for web applications
+ <p>
+ The web application policy divides includable
+ files into two distinct categories:
+ application-specific and site-wide. The former
+ includes files not intended for use outside of
+ the particular application in question, and the
+ latter addresses files intended for more
+ general use.
+ <p>
+ As previously mentioned, application-specific include
+ files should exist in a unique subdirectory of
+ <tt>/usr/share/<var>PACKAGE</var></tt>. This subdirectory
+ should exist outside of any web-accessible directory, as many
+ security-related problems in poorly written web applications
+ are the direct result of not doing so.
+
+ <sect id="libs-phplibs">PHP libraries
+ <p>
+ PHP libraries should be located in
+ <tt>/usr/share/php/<var>PACKAGE</var></tt>.
+ <p><em> FIXME: Perhaps PHP policy can eventually be split off into a seperate policy/manual, like perl?</em>
<sect id="libs-phpmods">PHP modules
<sect1 id="libs-phpmods-locations">PHP module locations
<p>
- Modules for PHP must be located
- in the following folder:
- <tt>/usr/lib/php<var>VERSION</var>/<var>PHP_API_VERSION</var></tt>
- <p><em>
- FIXME: Work out VERSION somehow.
- FIXME: Try and work out a less nasty way of getting the PHP_API_VERSION
- </em>
+ Precompiled binary modules for
+ PHP must be located in
+ <tt>/usr/lib/php<var>PHPVERSION</var>/<var>PHP_API_VERSION</var></tt>.
+ PHPVERSION is the numeric major
+ version number (such as 3, 4,
+ or 5), and PHP_API_VERSION is
+ the version against which the
+ module was compiled. The latter
+ is defined at build-time in
+ <tt>/usr/include/php<var>PHPVERSION</var></tt>/main/php.h.
+ <p>The following sed command can extract the value of
+ PHP_API_VERSION for php4:
<p>
- <var>PHP_API_VERSION</var> can be found with the following command:
- <tt>grep '\#define PHP_API_VERSION ' /usr/include/php4/main/php.h |sed 's/\#define PHP_API_VERSION //'</tt>
- <sect1 id="libs-phpmods-registering">Registering and unregistering a php module
- <p><em>FIXME sukria : should such a piece of code be provided by a webapps-common package?
-FIXME sean : same question as apache conf.d: symlinks or files? i'll assume
- symlinks below
-</em>
+ <tt>sed -ne 's/\#define PHP_API_VERSION //p' < /usr/include/php4/main/php.h</tt>
+
+ <sect1 id="libs-phpmods-registering">Registering and unregistering a PHP module
<p>
Applications extending the abilities
of php via add-on php modules should
@@ -383,83 +425,84 @@
the symbolic link in the php.d directory
(this makes seperating de-activation
from configuration purging possible).
- <p><em>
-FIXME sukria:
- Those piece of code sould be provided by our webapps-common package. The
- debconf question "do you want to register this php library?" should also be
- handled by our package, in the same philosophy than dbconfig-common: globalizing
- stuff, centralizing translations and improving maintenance.
- </em>
-
+
<chapt id="httpd"> Dealing with the webserver
- <sect id="httpd-register">Registering a web application with the server
- <sect1 id="httpd-register-symlinks">What about symlinking the document root?
+ <sect id="httpd-register">Registering a web application with a web server
+ <sect1 id="httpd-register-symlinks">Document roots
<p>
- The easiest way for registering a
- web application with the webserver
- is to symlink the document
- root of the package under the
- document root of the webserver
- (for instance <tt>/var/www</tt>).
+ Web applications should be
+ completely agnostic of the global
+ document root. All placement of
+ content should be compliant with
+ previously mentioned rules,
+ and not make any assumptions
+ about the content existing
+ in other locations, such
+ as <tt>/usr/local</tt>,
+ <tt>/var/www</tt> or
+ <tt>/srv</tt>. Such locations
+ are intended for use at the
+ discretion of the local
+ administrator.
<p>
- This is a bad idea and
- should not be done because
- the web applications should
- be completely agnostic of the
- document root. Doing so will
- lead to important drawbacks:
- <list>
- <item>it will be much harder to preserve the admin's preferences on upgrades (it would be hard to not recreate symlinks the admin deleted)
- <item>it makes assumptions about where the documentroot is
- <item>it could fail or overwrite non-package pre-existing data in the documentroot
- </list>
+ If possible, applications
+ should use the web server's
+ implementation of an "alias"
+ directive. For example,
+ in apache directive is named
+ "Alias". For web servers that do
+ not provide such a directive, the
+ local administrator is responsible
+ for placing symbolic links in
+ the document root to make an
+ application web-accessible.
+
+ <sect1 id="httpd-register-httpd">Registering and unregistering an application with web servers
<p>
- This approach should not be used
- to regiter a web application with
- the webserver. A better approach
- is to use web server aliases.
- <sect1 id="httpd-register-apache">Using Apache aliases
- <p><em>
-FIXME sukria:
- What to say for non apache web server?
- </em>
+ To register a web application with
+ a webserver, a package should
+ place the relevant webserver
+ configuration in a file under
+ <tt>/etc/<var>PACKAGE</var></tt> if
+ the target web server supports
+ drop-in configuration via a
+ configuration file directory (such
+ as the apache family of httpds'
+ <tt>conf.d</tt> directories) or
+ "include" configuration. In the
+ case of the latter, standard Debian
+ policy applies with respect to
+ the modification of the web
+ servers' configuration files. In
+ the case of the former, a symbolic
+ link should be used.
<p>
- To register the web
- application with the
- webeserver, a good approach is
- to place the webserver config in
- <tt>/etc/<var>PACKAGE</var>/apache.conf</tt>.
- Then, symlink to that to
- <tt>/etc/apache/conf.d/<var>PACKAGE</var>.conf</tt>.
+ If the target web server does
+ not support either of these
+ configuration mechanisms,
+ the package in question should
+ instead provide the configuration
+ as an example following standard
+ Debian documentation policy.
<p>
- The link should be removed on
- <tt>--remove</tt>, and then
- the package is disabled without
- removing configuration files,
- which should only be done on
- <tt>--purge</tt>.
+ Such configuration should only be
+ performed during installation. During
+ upgrade web applications must not take
+ any actions to enable or disable the
+ registration of an application, to
+ allow the local administrator to have
+ ultimate control.
<p>
- Note that the postinst script
- should only create the symlink
- when <tt>$2</tt> is empty (fresh
- install) and should do nothing
- when <tt>$2</tt> is present
- (upgrade).
- <p><em>
- FIXME sukria:
- this should be also provided by webapps-common (dh_webapp or a like).
- </em>
- <sect id="httpd-unreg">Unregistering a web application with the server
- <p>
- If the package fits this policy
- requirements, the application has
- been registered as described in <ref
- id="httpd-register-apache">, and then,
- uses Apache aliases
- <p>
- Unregsitering the webapp should then
- be as simple as removing the symlink
- <tt>/etc/apache/conf.d/<var>PACKAGE</var>.conf</tt>.
+ Unregistering a web application should be
+ handled by removing the symbolic link
+ in the case of <tt>conf.d</tt>-style directories.
+ In the case of "include" style directives,
+ standard Debian policy applies to modifying
+ web server configuration files.
+ <p>
+ During package removal, web applications
+ that register themselves with the web
+ server must unregister themselves.
<sect id="httpd-virtual">Enabling virtual hosting facilities
<p>
@@ -467,12 +510,10 @@
with the system administrator's chosen
httpd server under multiple ip based or
name based virtual hosts.
-
<p>
Several methods exist for registering
a web application with several virtual
hosts:
-
<list>
<item>
The apache module mod_env can be used
@@ -489,7 +530,6 @@
to provide configuration scripts for
the application
</list>
-
<p>
Under no circumstance should one instance
of an application interfere with another
@@ -497,15 +537,52 @@
<sect id="httpd-location">Default web location of package
<p>
- The package's static and
- architecture independent scripts
- should be accessable from
+ The static and dynamically interpreted
+ content of a web application should be
+ accessable from at or underneath
<tt>http://<var>servername</var>/<var>PACKAGE</var></tt>
- The package's architecture dependant
- scripts should be accessable from
+ The package's dynamically executed content may
+ also be accessible from
<tt>http://<var>servername</var>/cgi-bin/<var>PACKAGE</var></tt>
<chapt id="tools">Tools provided to help maintenance
+ <p>
+ While not strictly necessary, it's highly
+ recommended that package maintainers use
+ pre-existing tools to aid in packaging web
+ applications. This centralizes the effort not
+ only for the packageers themselves, but also
+ for translators and results in a much more
+ consistant feel for users of web applications:
+
<sect id="tools-db">dbconfig-common
+ <p>
+ dbconfig-common is an implementation
+ of the "best practices for database
+ applications" draft, which provides debian
+ packagers with an easy, reliable, and
+ consistant method for managing databases
+ used by debian packages.
+
+ <p>
+ dbconfig-common can:
+
+ <list>
+ <item> support mysql and postgresql applications
+ <item> create databases and database users
+ <item> access local or remote databases
+ <item> upgrade/modify databases when upstream changes database structure
+ <item> remove databases and database users
+ <item> generate config files in many formats with the database info.
+ <item> prompt users with a set of normalized, pre-translated questions
+ <item> do all the hard work automatically
+ <item> work for package maintainers with little effort on their part
+ <item> work for local admins with little effort on their part
+ <item> comply with an agreed upon set of standards for behaviour
+ <item> do absolutely nothing if it is the whim of the local admin
+ <item> perform all operations from within the standard flow of debian package maintainance (no additional skill is required of the local admin)
+ </list>
+
<sect id="tools-webapps">webapps-common
+
</book>
More information about the Webapps-common-discuss
mailing list