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 /srv, /var/www or /usr/local.
Specifically, the following table should serve as a guideline for the placement of files:
/usr/share/PACKAGE/www
A unique subdirectory of either /usr/lib/cgi-bin/PACKAGE or /usr/lib/PACKAGE (architecture-dependant)
A unique subdirectory of /usr/share/PACKAGE (architecture-independant)
A unique subdirectory of /usr/share/PACKAGE
A unique subdirectory of /usr/share/PACKAGE
Cached and regenerated application data
rrd, mrtg and other database files
/etc/PACKAGE
A subdirectory of /etc/PACKAGE
/usr/share/php/PACKAGE
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 /etc, in a directory specific to the package in question.
Often the upstream authors of software will ship a configuration file that is located underneath the web root of the application. The local administrator must not be required to edit these files because package upgrades could lead to loss of such configuration.
The best way to work around such a problem is by using the appropriate "include" construct for the language in question. to include a smaller, trimmed down configuration file from /etc/PACKAGE. In PHP this would be require_once, and in perl this would be use.
Web application configuration files may 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. TODO: should configuration files generated via a web interface exist in /etc, or in /var/lib as included files?
The following table reflects the requirements for configuration file permissions and ownership
Ownership: root:www-data
Permissions: 640
Ownership: root:www-data
Permissions: 644
Ownership: root:www-data
Permissions: 660
Static content can be divided into smaller subsets based on their nature:
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.
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 /usr/local/PACKAGE. Managing the latter is outside the scope of this document.
If the web application needs a database to run properly, it must abide by the
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 dbconfig-common
manual
for more information.
Scripts that shouldn't normally need to exist in the standard system path should follow the standard Debian policy and exist in /usr/share/PACKAGE.
However, web applications have the additional requirement that if such scripts are not intended to be directly accessed via the web, they must not exist under the document root or other directly web-accessible location. Scripts intended for execution or interpretation via the web must exist in locations where their underlying source code can be directly retrieved.
The policy for Architecture dependant binaries should follow the general rules of the FHS and Debian policy, and exist in /usr/lib/PACKAGE. Additionally, policy permits these files to exist in /usr/lib/cgi-bin/PACKAGE though this may become deprecated in the future.
Similar to Architecture-independent files, if such files are intended to be executed via the web, they must not exist in a location where they can be directly retrieved.
Webapps Policy Manual
$Revision: 1.15 $