[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.sgml,1.11,1.12
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-serv13730
Modified Files:
Webapps-Policy-Manual-DRAFT.sgml
Log Message:
another large chunk of work done, clarifications and additions.
Index: Webapps-Policy-Manual-DRAFT.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/Webapps-Policy-Manual-DRAFT.sgml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -d -r1.11 -r1.12
--- Webapps-Policy-Manual-DRAFT.sgml 5 Jul 2005 23:45:58 -0000 1.11
+++ Webapps-Policy-Manual-DRAFT.sgml 6 Jul 2005 01:09:18 -0000 1.12
@@ -46,9 +46,13 @@
This manual aims to clarify the
standards and technical requirements
for web-based software in the Debian
- GNU/Linux distribution.
+ GNU/Linux distribution. It also serves as
+ packaging manual with examples of best
+ practices for packaging web applications
+ in Debian.
<p>
- Web-based software encompasses the group
+ "Web-based software", or "Web
+ applications", encompass the group
of software packages which are designed to
be accessed via the Hyper Text Transfer
Protocol (HTTP) and similar client/server based
@@ -94,37 +98,55 @@
<p>
<taglist>
<tag><item>
- <p><strong>httpd</strong>
- <p>Any server providing http
+ <p><strong>httpd and web-server</strong>
+ <p>Any server providing content via the Hyper Text Transfer Protocol.
<tag><item>
<p><strong>Web application</strong>
- <p>A suite of static/dynamic pages for common purpose
+ <p>A suite of static and dynamic
+ content, as well as any other
+ associated scripts and data
+ serving a common purpose.
<tag><item>
- <p><strong>Static pages</strong>
- <p>Pages requiring no server interpretation/execution
+ <p><strong>Static content</strong>
+ <p>Read-only content served without
+ requiring server interpretation
+ or execution.
<tag><item>
- <p><strong>Dynamically interpreted pages</strong>
- <p>Pages requiring server interpretation to generate web content. <em>Most PHP applications are based from this type of content.</em>
+ <p><strong>Dynamically interpreted content</strong>
+ <p>Architecture-independant
+ content requiring server
+ interpretation. <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><strong>Dynamically executed content</strong>
+ <p>Similar to interpreted content,
+ but instead of requiring the server
+ to interpret the underlying
+ file(s), content is obtained
+ by execution of a script or
+ binary. <em>Most packages
+ using a "cgi-bin" would fall
+ under this category.</em>
+ <tag><item>
+ <p><strong>Cached content</strong>
+ <p>Content that can be reconstituted
+ from existing data, such as proxied
+ data or graph images generated
+ from databases.
+ <tag><item>
+ <p><strong>Include files</strong>
+ <p>Architecture-independant files
+ referenced by dynamic content
+ providing functionality but not
+ directly accessed from the web.
+ <tag><item>
+ <p><strong>Include libraries</strong>
+ <p>The subset of include files intended
+ for site wide use by multiple
+ applications.
</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.
- <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
@@ -133,49 +155,49 @@
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.
+ places such as /srv, /var/www or /usr/local.
<p>
Specifically, the following table should
- serve as guidelines for the location
+ serve as a guideline for the placement
of files:
<p>
<taglist>
<tag><item>
- <p><strong>static/dynamically interpreted web pages</strong>
+ <p><strong>Static and dynamically interpreted content</strong>
<p><em><tt>/usr/share/<var>PACKAGE</var>/www</tt></em>
<tag><item>
- <p><strong>application-specific libraries</strong>
- <p><em><tt>/usr/share/<var>PACKAGE</var>/include</tt></em>
- <tag><item>
- <p><strong>other helper scripts that don't belong in <tt>/usr/bin</tt></strong>
- <p><em><tt>/usr/share/<var>PACKAGE</var>/scripts</tt></em>
+ <p><strong>Dynamically executed content</strong>
+ <p>A unique subdirectory of either
+ <em><tt>/usr/lib/cgi-bin/<var>PACKAGE</var></tt></em>
+ or
+ <em><tt>/usr/lib/<var>PACKAGE</var></tt></em>
+ (architecture-dependant)
+ <p>A unique subdirectory of <em><tt>/usr/share/<var>PACKAGE</var></tt></em> (architecture-independant)
<tag><item>
- <p><strong>persistent application data</strong>
- <p><em><tt>/var/lib/<var>PACKAGE</var></tt></em>
+ <p><strong>Application-specific include files</strong>
+ <p>A unique subdirectory of <em><tt>/usr/share/<var>PACKAGE</var></tt></em>
<tag><item>
- <p><strong>cached/regenerated application data</strong>
- <p><em><tt>/var/cache/<var>PACKAGE</var></tt></em>
+ <p><strong>Other static data, and helper scripts that don't belong in users' paths</strong>
+ <p>A unique subdirectory of <em><tt>/usr/share/<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>
+ <p><strong>Persistent application data</strong>
+ <p><strong>Cached and regenerated application data</strong>
+ <p><strong>rrd, mrtg and other database files</strong>
+ <p><em>See
+ <url id="http://people.debian.org/~seanius/policy/dbapp-policy.html" name="database application policy">.
<tag><item>
- <p><strong>site configuration (settings/passwords)</strong>
+ <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><strong>Modifiable and overridable content</strong>
+ <p>A subdirectory of <em><tt>/etc/<var>PACKAGE</var></tt></em>
<tag><item>
- <p><strong>php libraries</strong>
+ <p><strong>PHP includable 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>
+ <p><strong>Perl includable libraries</strong>
+ <p>See <url id="http://www.debian.org/doc/packaging-manuals/perl-policy/" name="Debian Perl Policy">
+ <tag><item>
</taglist>
<sect id="issues-conf">Configuration Files and Customizable Content
@@ -191,22 +213,24 @@
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.
+ the application. The local administrator
+ must not be required to edit these
+ files because package upgrades could
+ lead to loss of such 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,
+ problem is by using the appropriate
+ "include" construct for the language
+ in question. to include a smaller,
trimmed down configuration file from
- underneath <tt>/etc</tt>.
+ <tt>/etc/<var>PACKAGE</var></tt>.
+ In PHP this would be
+ <tt>require_once</tt>, and in perl this
+ would be <tt>use</tt>.
+
<sect1 id="issues-conf-perm">Permissions and Ownership of Configuration Files
<p>
- Webapp configuration files will
+ Web application configuration files may
likely need to have permissions
and ownership different from
the standard root:root ownership
@@ -225,81 +249,68 @@
able to prevent this behaviour
by changing the file permissions
via dpkg-statoverride.
+
+ <em>TODO</em>: should
+ configuration files generated via
+ a web interface exist in /etc,
+ or in /var/lib as included files?
<p>
The following table reflects the
requirements for configuration
file permissions and ownership
<taglist>
<tag><item>
- <p><strong>sensitive settings/passwords</strong>
+ <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><strong>Non-sensitive settings (themes, etc)</strong>
<p>Ownership: <tt>root:www-data</tt>
<p>Permissions: <tt>644</tt>
<tag><item>
- <p><strong>application-editable configuration</strong>
+ <p><strong>Application-modifiable 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:
+ <sect id="issues-static">Static content
+ Static content can be divided into smaller subsets
+ based on their nature:
<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.
+ <item>Templates and stylesheets used to generate dynamic pages.
+ <item>Graphical images such as JPEG, PNG, and GIF format 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.
+ Static content provided by the package
+ should be considered read-only data.
+ The local administrator should not
+ be required to modify such files. Content
+ requiring or suggesting modification for
+ customizing a web application must not
+ exist in the same location as standard
+ package-provided content.
<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.
+ If a web application supports using an
+ alternate location for customized content,
+ it should either follow the previously
+ mentioned guidelines for configuration and
+ customizable content or use a subdirectory
+ of <tt>/usr/local/<var>PACKAGE</var></tt>.
+ Managing the latter is outside the scope
+ of this document.
</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.
+ 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
+ more information.
+
<sect id="issues-archindep">Architecture independent scripts (Perl, PHP and others)
<p><em> FIXME