[Webapps-common-discuss] webapps-common/doc Webapps-Policy-Manual-DRAFT.txt,1.13,1.14
sukria-guest@haydn.debian.org
sukria-guest@haydn.debian.org
Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/tmp/cvs-serv9781/doc
Modified Files:
Webapps-Policy-Manual-DRAFT.txt
Log Message:
updates from the last thread: resitering webapp...
Index: Webapps-Policy-Manual-DRAFT.txt
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/Webapps-Policy-Manual-DRAFT.txt,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- Webapps-Policy-Manual-DRAFT.txt 9 May 2005 15:52:59 -0000 1.13
+++ Webapps-Policy-Manual-DRAFT.txt 10 May 2005 07:50:43 -0000 1.14
@@ -85,8 +85,10 @@
that each web application package must satisfy to be included in the
distribution.
-It has been seen that there are more and more web applications entering Debian
-and they are getting more and more importance
+More and more web applications are packaged in Debian but the current Debian
+Policy Manual[1] does not give guidelines to help web applications maintainers.
+
+This Policy Manual aims to fill this blank.
Each package that provides an application available through a web interface is
supposed to be compliant with this policy manual.
@@ -130,7 +132,7 @@
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.
-specifically, the following table should serve as guidelines for the
+Specifically, the following table should serve as guidelines for the
location of files:
type of file location
@@ -143,10 +145,7 @@
site configuration (settings/passwords) /etc/PACKAGE
locally modifiable/overridable content /etc/PACKAGE****
php libraries /usr/share/php/PACKAGE
-Architecture independant Perl libraries /usr/share/perl5/PACKAGE
-Architecture dependant Perl libraries /usr/lib/perl5/PACKAGE
rrd, mrtg and other database files see database application policy
-Template cache files /var/cache/PACKAGE/templates
*: also acceptable are "htdocs", "site", or any other name, as long as
it is clearly identifying and a subdirectory of /usr/share/PACKAGE. this
@@ -193,6 +192,7 @@
FIXME: maybe we should add this to the above table, with specs for all files?
file type/content ownership permissions
+------------------------------------------------------------------------
sensitive settings/passwords root:www-data 640
non-sensitive data (themes, etc) root:www-data 644
application-editable configuration root:www-data 660
@@ -209,36 +209,34 @@
. images: jpg, png or gif image files.
. web pages: full HTML pages used without dynamic change.
-FIXME : there are two main points of view for static files, remains to choose
- which one to keep.
-
-* Static files are conffiles *
-
-...
-
-* Static files are readonly data *
-
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.
+content needed by the application and should not be modified in-place.
-Thus, every static file should be put under /usr/share/$package.
+Thus, every static file should be put under /usr/share/$package. As suggested in
+section 2.1, using /usr/share/$package/www for the document root is a good idea.
If there is a way to provide an alternate location for the static contents, the
user could be pointed to the /usr/local/$package directory and should be advised
to copy the /usr/share/$package content inside.
He will then be able to handle his modifications safely.
-FIXME: please comment on this section....
+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.
+
2.3 Database issues
-If the web application needs a database to run properly, the maintainer must use
+If the web application needs a database to run properly, the maintainer should use
the dbconfig-common package to perform the database configuration.
-See the dbconfig-common manual for details...
+Please see the dbconfig-common manual[1] for details about how using this package.
-FIXME: more details, reference...
+1: http://people.debian.org/~seanius/policy/examples/dbconfig-common/doc/dbconfig-common.html
2.4 Architecture independent scripts (Perl, PHP and others)
@@ -327,46 +325,77 @@
done
--- SAMPLE CODE ---
-FIXME: Should this lot be handled by debconf?
+FIXME:
+ Should this lot be handled by debconf?
+FIXME sukria:
+ Yes.
+ 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.
-3.2 Perl modules
-
4 Dealing with the webserver
---------------------------------------------------------------------
4.1 Registering a web application with the server
-4.1.1 Symlinking the document root
+4.1.1 What about symlinking the document root?
-One of the easiest way to register the web application with the web server is to
-symlink the document root of the web application under /var/www.
+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 /var/www).
-For instance, a web application is likely to put its document root under
-/usr/share/bugzilla/www (as suggested on section 2.1) and should then add a
-symlink like that:
-
- /var/www/package -> /usr/share/package
+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 the easiest way to make the web site visible from the web server
-(accessing http://host/package/ is now possible).
+ . it will be much harder to preserve the admin's preferences on upgrades
+ (it would be hard to not recreate symlinks the admin deleted)
-4.1.2 Adding a Location to the webserver configuration
+ . it makes assumptions about where the documentroot is
-There is a more complex way of regitering the web application which may be
-better than the previous one
+ . it could fail or overwrite non-package pre-existing data in the
+ documentroot
+
+This approach should not be used to regiter a web application with the
+webserver. A better approach is to use web server aliases.
-FIXME sukria: ... to be continued ...
+4.1.2 Using Apache aliases
-FIXME sukria: find other ways ...
+FIXME sukria:
+ What to say for non apache web server?
+
+To register the web application with the webeserver, a good approach is to place
+the webserver config in /etc/$package/apache.conf. Then, symlink to that to
+/etc/$apache/conf.d/$package.conf.
+
+The link should be removed on --remove, and then the package is
+disabled without removing configuration files, which should only be done
+on --purge.
+
+Note that the postinst script should only create the symlink when $2 is empty
+(fresh install) and should do nothing when $2 is present (upgrade).
+
+FIXME sukria:
+ this should be also provided by webapps-common (dh_webapp or a like).
4.2 Unregistering a web application with the server
+If the package fits this policy requirements, the application has been
+registered as describe in section 4.1.2, and then, uses Apache aliases
+
+Unregsitering the webapp should then be as simple as removing the symlink
+/etc/$apache/conf.d/$package.conf.
+
4.3 Enabling virtual hosting facilities
4.4 Providing different upstream versions at the same time
+FIXME sukria:
+ Not in the scope of this policy?
+
5 Tools provided to help maintenance
---------------------------------------------------------------------