[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.sgml,NONE,1.1
neilm@haydn.debian.org
neilm@haydn.debian.org
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/tmp/cvs-serv9375
Added Files:
Webapps-Policy-Manual-DRAFT.sgml
Log Message:
Now using debiandoc SGML!
--- NEW FILE: Webapps-Policy-Manual-DRAFT.sgml ---
<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN">
<book>
<title>Webapps Policy Manual
<author>Alexis Sukrieh
<author>Pascal Hakim
<author>Neil McGovern
<author>Sean Finney
<version>
$Revision: 1.1 $
<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.
<copyright>
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.
<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.
<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.
<toc sect1>
<chapt id="about">About this manual
<sect id="about-scope">Scope
<p>
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.
<p>
More and more web applications are packaged in Debian but the current <url id="http://www.debian.org/doc/debian-policy/" name="Debian
Policy Manual"> does not give guidelines to help web applications maintainers.
<p>
This Policy Manual aims to fill this blank.
<p>
Each package that provides an application available through a web interface is
supposed to be compliant with this policy manual.
<sect id="about-authors">Authors and Maintainers
<p>
This policy manual has been written by the members of the Debian Webapps Team:
<p>
<list>
<item>Alexis Sukrieh
<item>Pascal Hakim
<item>Neil McGovern
<item>Sean Finney
</list>
<p>
<em>FIXME: add here your name ;)</em>
<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.
<sect id="about-related">Related Documents
<p>
FIXME: This Policy is deeply bound to the Debian Policy Manual...
<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.
<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.
<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.
<p>
Specifically, the following table should serve as guidelines for the
location of files:
<p>
<taglist>
<tag><item>
<p><strong>static/dynamically interpreted web pages</strong>
<p><em><tt>/usr/share/<var>PACKAGE</var>/www</tt></em>
<p>
Also acceptable are "htdocs", "site", or any other name, as long as
it is clearly identifying and a subdirectory of <tt>/usr/share/<var>PACKAGE</var></tt>. This
will allow other non-web-accessible data to also be stored in the parent
directory.
<tag><item>
<p><strong>persistent application data</strong>
<p><em><tt>/var/lib/<var>PACKAGE</var></tt></em>
<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>
<tag><item>
<p><strong>application-specific libraries</strong>
<p><em><tt>/usr/share/<var>PACKAGE</var>/include</tt></em>
<p>
Other names, such as "lib" or "functions" are acceptable, as is anything
else, as long as it is identifiable, outside the documentroot, and in
a subdirectory of <tt>/usr/share/<var>PACKAGE</var></tt>
<tag><item>
<p><strong>site configuration (settings/passwords)</strong>
<p><em><tt>/etc/<var>PACKAGE</var></tt></em>
<tag><item>
<p><strong>locally modifiable/overridable content</strong>
<p><em><tt>/etc/<var>PACKAGE</var>templates</tt></em>
<p>
Once again, "templates" could be substituted with anything else
that makes sense, as long as it is a subdirectory of <tt>/etc/<var>PACKAGE</var></tt>
<tag><item>
<p><strong>php libraries</strong>
<p><em><tt>/usr/share/php/<var>PACKAGE</var></tt></em>
<tag><item>
<p><strong>rrd, mrtg and other database files</strong>
<p><em>See database application policy</em>
</taglist>
<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.
<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.
<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>.
<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.
<p>
The following table reflects the requirements for configuration file
permissions and ownership
<taglist>
<tag><item>
<p><strong>sensitive settings/passwords</strong>
<p>Ownership: <tt>root:www-data</tt>
<p>Permissions: <tt>640</tt>
<tag><item>
<p><strong>non-sensitive data (themes, etc)</strong>
<p>Ownership: <tt>root:www-data</tt>
<p>Permissions: <tt>644</tt>
<tag><item>
<p><strong>application-editable configuration</strong>
<p>Ownership: <tt>root:www-data</tt>
<p>Permissions: <tt>660</tt>
</taglist>
<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".
<p>
There are a couple of static files:
<list>
<item>templates: some html or css pages used to generate dynamic pages.
<item>images: jpg, png or gif image files.
<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.
<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.
<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.
<p><em>FIXME: quoting sean:
for those who absolutely want the ability to edit all of
these files, we've discussed the feasibility of generating a tool
that would assist in this, and it seems fairly reasonable that we
could do it.
</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.
<sect id="issues-archindep">Architecture independent scripts (Perl, PHP and others)
<p><em> FIXME
Where to put them ?
/usr/share/$package ?
</em>
<sect id="issues-archdep">Architecture dependant scripts
<p><em> FIXME
Is /usr/lib/cgi-bin still valid?
</em>
<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>
<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>
<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>
<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".
<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).
<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?
<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>).
<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>
<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>
<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>.
<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>.
<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>.
<sect id="httpd-virtual">Enabling virtual hosting facilities
<sect id="httpd-versions">Providing different upstream versions at the same time
<p><em>
FIXME sukria:
Not in the scope of this policy?
</em>
<chapt id="tools">Tools provided to help maintenance
<sect id="tools-db">dbconfig-common
<sect id="tools-webapps">webapps-common
</book>