[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.sgml,1.10,1.11
seanius@haydn.debian.org
seanius@haydn.debian.org
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv16149
Modified Files:
Webapps-Policy-Manual-DRAFT.sgml
Log Message:
heavy handed 80-column formatting
Index: Webapps-Policy-Manual-DRAFT.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/Webapps-Policy-Manual-DRAFT.sgml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- Webapps-Policy-Manual-DRAFT.sgml 5 Jul 2005 23:41:02 -0000 1.10
+++ Webapps-Policy-Manual-DRAFT.sgml 5 Jul 2005 23:45:58 -0000 1.11
@@ -8,28 +8,36 @@
<version>
$Revision$
<abstract>
- This manual describes the policy requirements for the packaging of web
- application in the Debian GNU/Linux distribution.
- This includes a description of the scope covered by this policy section,
- several design issues of web applications, as well as technical requirements
- that each web application package must satisfy to be included in the
- distribution.
+ This manual describes the policy requirements for the
+ packaging of web application in the Debian GNU/Linux
+ distribution. This includes a description of the scope
+ covered by this policy section, several design issues
+ of web applications, as well as technical requirements
+ that each web application package must satisfy to be
+ included in the distribution.
<copyright>
- Copyright © 2005 The Debian Webapps Team <email>debian-webapps@lists.debian.org</email>.
+ Copyright © 2005 The Debian Webapps Team
+ <email>debian-webapps@lists.debian.org</email>.
<p>
- This manual is free software; you may redistribute it and/or modify it under
- the terms of the GNU General Public License as published by the Free Software
- Foundation; either version 2, or (at your option) any later version.
+ This manual is free software; you may redistribute
+ it and/or modify it under the terms of the GNU
+ General Public License as published by the Free
+ Software Foundation; either version 2, or (at
+ your option) any later version.
<p>
- This is distributed in the hope that it will be useful, but without any
- warranty; without even the implied warranty of merchantability or fitness for
- a particular purpose. See the GNU General Public License for more details.
+ This is distributed in the hope that it will
+ be useful, but without any warranty; without
+ even the implied warranty of merchantability or
+ fitness for a particular purpose. See the GNU
+ General Public License for more details.
<p>
- A copy of the GNU General Public License is available as
- /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the
- World Wide Web at the GNU General Public Licence. You can also obtain it by
- writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ A copy of the GNU General Public License is
+ available as /usr/share/common-licenses/GPL in the
+ Debian GNU/Linux distribution or on the World Wide
+ Web at the GNU General Public Licence. You can
+ also obtain it by writing to the Free Software
+ Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
<toc sect1>
<chapt id="about">About this manual
@@ -60,11 +68,16 @@
<item>Sean Finney
</list>
<p>
- While the authors of this document have tried hard to avoid typos and other
- errors, these do still occur. If you discover an error in this manual or if you
- want to give any comments, suggestions, or criticisms please send an email to
- the Debian Webapps List, <email>debian-webapps@lists.debian.org</email>, or submit a bug report
- against the <package>webapps-common</package> package.
+ While the authors of this document
+ have tried hard to avoid typos and
+ other errors, these do still occur. If
+ you discover an error in this manual
+ or if you want to give any comments,
+ suggestions, or criticisms please send
+ an email to the Debian Webapps List,
+ <email>debian-webapps@lists.debian.org</email>,
+ or submit a bug report against the
+ <package>webapps-common</package> package.
<sect id="about-related">Related Documents
<p>
"Web applications" is a fairly broad
@@ -94,26 +107,37 @@
<p>Pages requiring server interpretation to generate web content. <em>Most PHP applications are based from this type of content.</em>
<tag><item>
<p><strong>Dynamically executed pages</strong>
- <p>Similar to interpreted pages, but instead of interpretation the content is obtained by execution of a script or binary. <em>Most packages using a "cgi-bin" would fall under this category.</em>
+ <p>Similar to interpreted pages,
+ but instead of interpretation the
+ content is obtained by execution
+ of a script or binary. <em>Most
+ packages using a "cgi-bin" would
+ fall under this category.</em>
</taglist>
<chapt id="issues">Common issues and recommended solutions
<p>
- Packaging a web application is much hard than it could seem in the first place.
- A web application comes with a couple of kinds of files which should be handled
- with care.
+ Packaging a web application is much hard than it
+ could seem in the first place. A web application
+ comes with a couple of kinds of files which
+ should be handled with care.
<p>
- This section will cover every common issue a webapp maintainer can face. Most of
- the points covered here are mandatory if you want your package to be included in
- the Debian Archive.
+ This section will cover every common issue a
+ webapp maintainer can face. Most of the points
+ covered here are mandatory if you want your
+ package to be included in the Debian Archive.
<sect id="issues-fhs">Web applications and the FHS
<p>
- Web applications should follow the same guidelines as any other
- software. Most specifically, they should not make any assumption about
- how the administrator has arranged the file hierarchy outside of the FHS
- by placing files in non-standard places such as /var/www or /usr/local.
+ Web applications should follow the same
+ guidelines as any other software. Most
+ specifically, they should not make any
+ assumption about how the administrator
+ has arranged the file hierarchy outside of
+ the FHS by placing files in non-standard
+ places such as /var/www or /usr/local.
<p>
- Specifically, the following table should serve as guidelines for the
- location of files:
+ Specifically, the following table should
+ serve as guidelines for the location
+ of files:
<p>
<taglist>
<tag><item>
@@ -134,9 +158,12 @@
<tag><item>
<p><strong>dynamcially executed web pages</strong>
<p><em><tt>/usr/lib/cgi-bin/<var>PACKAGE</var></tt></em>
- <p>
- What to do with non-architecture-specific executable files is up
- for debate. Another possible location would be <tt>/usr/share/<var>PACKAGE</var>/cgi-bin</tt>
+ <p> What to do with
+ non-architecture-specific
+ executable files is up for
+ debate. Another possible location
+ would be
+ <tt>/usr/share/<var>PACKAGE</var>/cgi-bin</tt>
<tag><item>
<p><strong>site configuration (settings/passwords)</strong>
<p><em><tt>/etc/<var>PACKAGE</var></tt></em>
@@ -153,33 +180,55 @@
<sect id="issues-conf">Configuration Files and Customizable Content
<p>
- In-line with standard FHS policy, any files that require being edited by
- the local administrator (for information such as "themes" or credentials
- to a database) must be located under <tt>/etc</tt>, in a directory specific to
- the package in question.
+ In-line with standard FHS policy, any
+ files that require being edited by the
+ local administrator (for information such
+ as "themes" or credentials to a database)
+ must be located under <tt>/etc</tt>,
+ in a directory specific to the package
+ in question.
<p>
- Often the upstream authors of software will ship a configuration file
- that is located underneath the web root of the application. the admin
- must not be required to edit these files because package upgrades could
- lead to loss of this configuration.
+ Often the upstream authors of software
+ will ship a configuration file that
+ is located underneath the web root of
+ the application. the admin must not be
+ required to edit these files because
+ package upgrades could lead to loss of
+ this configuration.
<p>
- The best way to work around such a problem is by using whatever is
- the appropriate "include" construct for the language in question (in
- PHP this would be <tt>require_once</tt>, in perl <tt>use</tt>) to include a smaller,
- trimmed down configuration file from underneath <tt>/etc</tt>.
+ The best way to work around such a
+ problem is by using whatever is the
+ appropriate "include" construct for
+ the language in question (in PHP this
+ would be <tt>require_once</tt>, in perl
+ <tt>use</tt>) to include a smaller,
+ trimmed down configuration file from
+ underneath <tt>/etc</tt>.
<sect1 id="issues-conf-perm">Permissions and Ownership of Configuration Files
<p>
- Webapp configuration files will likely need to have permissions and ownership
- different from the standard root:root ownership and 644 permissions. The most
- notable reason for this is that the webserver usually needs the ability to
- read some of these configuration files. Note that some applications provide
- the ability to edit their configuration via a web-based interface. In such
- a case, the files should be writable by the www-data group. The local
- administrator should always be able to prevent this behaviour by changing the
- file permissions via dpkg-statoverride.
+ Webapp configuration files will
+ likely need to have permissions
+ and ownership different from
+ the standard root:root ownership
+ and 644 permissions. The most
+ notable reason for this is that
+ the webserver usually needs
+ the ability to read some of
+ these configuration files. Note
+ that some applications provide
+ the ability to edit their
+ configuration via a web-based
+ interface. In such a case,
+ the files should be writable by
+ the www-data group. The local
+ administrator should always be
+ able to prevent this behaviour
+ by changing the file permissions
+ via dpkg-statoverride.
<p>
- The following table reflects the requirements for configuration file
- permissions and ownership
+ The following table reflects the
+ requirements for configuration
+ file permissions and ownership
<taglist>
<tag><item>
<p><strong>sensitive settings/passwords</strong>
@@ -197,8 +246,10 @@
<sect id="issues-static">Static files
<p>
- Every files needed by the web application and provided as static content (html,
- images or css) are called in this document "static files".
+ Every files needed by the web application
+ and provided as static content (html,
+ images or css) are called in this document
+ "static files".
<p>
There are a couple of static files:
<list>
@@ -207,17 +258,28 @@
<item>web pages: full HTML pages used without dynamic change.
</list>
<p>
- Every static files provided by the package are considered read-only data.
- The user should not touch those files. This is the default version of the static
- content needed by the application and should not be modified in-place.
+ Every static files provided by the package
+ are considered read-only data. The user
+ should not touch those files. This is the
+ default version of the static content
+ needed by the application and should
+ not be modified in-place.
<p>
- Thus, every static file should be put under <tt>/usr/share/<var>PACKAGE</var></tt>. As suggested in
- <ref id="issues-fhs">, using <tt>/usr/share/<var>PACKAGE</var>/www</tt> for the document root is a good idea.
+ Thus, every static
+ file should be put under
+ <tt>/usr/share/<var>PACKAGE</var></tt>. As
+ suggested in <ref id="issues-fhs">, using
+ <tt>/usr/share/<var>PACKAGE</var>/www</tt>
+ for the document root is a good idea.
<p>
- If there is a way to provide an alternate location for the static contents, the
- user could be pointed to the <tt>/usr/local/<var>PACKAGE</var></tt> directory and should be advised
- to copy the <tt>/usr/share/<var>PACKAGE</var></tt> content inside.
- He will then be able to handle his modifications safely.
+ If there is a way to provide an alternate
+ location for the static contents,
+ the user could be pointed to the
+ <tt>/usr/local/<var>PACKAGE</var></tt>
+ directory and should be advised to copy
+ the <tt>/usr/share/<var>PACKAGE</var></tt>
+ content inside. He will then be able
+ to handle his modifications safely.
<p><em>FIXME: quoting sean:
for those who absolutely want the ability to edit all of
@@ -227,12 +289,17 @@
</em>
<sect id="issues-database">Database issues
<p>
- If the web application needs a database to run properly, it must abide by
- the <url id="http://people.debian.org/~seanius/policy/dbapp-policy.html" name="database application policy">. The maintainer is highly encouraged
- to use a common tool such as dbconfig-common to perform the database
- configuration. Please see the <url id="http://people.debian.org/~seanius/policy/dbconfig-common-using.html" name="dbconfig-common manual"> for details
- about how using this package.
-
+ If the web application needs a database
+ to run properly, it must abide by the <url
+ id="http://people.debian.org/~seanius/policy/dbapp-policy.html"
+ name="database application
+ policy">. The maintainer is highly
+ encouraged to use a common tool such as
+ dbconfig-common to perform the database
+ configuration. Please see the <url
+ id="http://people.debian.org/~seanius/policy/dbconfig-common-using.html"
+ name="dbconfig-common manual"> for
+ details about how using this package.
<sect id="issues-archindep">Architecture independent scripts (Perl, PHP and others)
<p><em> FIXME
@@ -251,7 +318,8 @@
<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:
+ 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.
@@ -266,18 +334,27 @@
symlinks below
</em>
<p>
- Applications extending the abilities of php via add-on php modules should
- do so by placing symbolic links to any any relevant configuration files
- in the appropriate <tt>php.d</tt> directory (<tt>/etc/php4/apache/php.d</tt>, for
- example). Editing the contents of <tt>php.ini</tt> files directly is strongly
- discouraged and should only be done if it is not possible to make changes
- via the previously described method. In such cases, packages must not
- do so without first prompting the admin, and the default response for such
- a question should be "false".
+ Applications extending the abilities
+ of php via add-on php modules should
+ do so by placing symbolic links to any
+ any relevant configuration files in the
+ appropriate <tt>php.d</tt> directory
+ (<tt>/etc/php4/apache/php.d</tt>,
+ for example). Editing the contents
+ of <tt>php.ini</tt> files directly is
+ strongly discouraged and should only be
+ done if it is not possible to make changes
+ via the previously described method.
+ In such cases, packages must not do so
+ without first prompting the admin, and
+ the default response for such a question
+ should be "false".
<p>
- Upon package removal, packages can de-register themselves by simply
- removing the symbolic link in the php.d directory (this makes seperating
- de-activation from configuration purging possible).
+ Upon package removal, packages can
+ de-register themselves by simply removing
+ 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
@@ -290,47 +367,70 @@
<sect id="httpd-register">Registering a web application with the server
<sect1 id="httpd-register-symlinks">What about symlinking the document root?
<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>).
+ 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>).
<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:
+ 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>
<p>
- This approach should not be used to regiter a web application with the
- webserver. A better approach is to use web server aliases.
+ 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>
<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
+ 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>.
<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>.
+ 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>.
<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).
+ 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
+ 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
+ Unregsitering the webapp should then
+ be as simple as removing the symlink
<tt>/etc/apache/conf.d/<var>PACKAGE</var>.conf</tt>.
<sect id="httpd-virtual">Enabling virtual hosting facilities
@@ -369,8 +469,13 @@
<sect id="httpd-location">Default web location of package
<p>
- The package's static and architecture independent scripts should be accessable from <tt>http://<var>servername</var>/<var>PACKAGE</var></tt>
- The package's architecture dependant scripts should be accessable from <tt>http://<var>servername</var>/cgi-bin/<var>PACKAGE</var></tt>
+ The package's static and
+ architecture independent scripts
+ should be accessable from
+ <tt>http://<var>servername</var>/<var>PACKAGE</var></tt>
+ The package's architecture dependant
+ scripts should be accessable from
+ <tt>http://<var>servername</var>/cgi-bin/<var>PACKAGE</var></tt>
<chapt id="tools">Tools provided to help maintenance
<sect id="tools-db">dbconfig-common