--- xml/htdocs/proj/en/glep/glep-0011.html 2003/08/07 19:06:01 1.1 +++ xml/htdocs/proj/en/glep/glep-0011.html 2003/08/12 17:02:43 1.2 @@ -33,9 +33,9 @@ Title:Web Application Installation -Version:1.1 +Version:1.2 -Last-Modified:2003/08/07 19:02:40 +Last-Modified:2003/08/12 23:14:00 Author:Troy Dack <tad at gentoo.org> @@ -49,7 +49,7 @@ Created:02 August 2003 -Post-History:07 Aug 2003 +Post-History:07 Aug 2003, 12 Aug 2003 @@ -57,50 +57,49 @@

Contents

-

Credits

+

Credits

Based on comments posted to gentoo-dev mailing list [1] [2] [3] by:

-Stuart Herbert <stuart@gentoo.org>, Max Kalika <max@gentoo.org>, -Robin H.Johnson <robbat2@gentoo.org> and others
+Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>, +Robin H.Johnson <robbat2 at gentoo.org> and others
-

Definitions

+

Definitions

Web Application
@@ -121,7 +120,7 @@
-

Conventions

+

Conventions

When describing the location of a directory in the file system it wil be shown with a trailing slash, eg:

@@ -136,11 +135,11 @@
-

Abstract

+

Abstract

To define where and how web based applications should be installed by Gentoo.

-

Motivation

+

Motivation

Currently there is no standard defined regarding the installation of web based applicaitons in Gentoo. This leads to ebuild authors creating a variety of methods to determine:

@@ -158,7 +157,7 @@ after an upgrade.

-

Rationale

+

Rationale

A discussion on the gentoo-dev mailing list [1] raised the following points regarding how Gentoo handles the installation of web based applications:

@@ -171,7 +170,7 @@ under the Document Root of a web server.

    -
  1. Web Application must be slotted by their major version numbers to +
  2. Web Application must be slotted by their full version numbers to further avoid downtime when true configuration changes are required.
@@ -188,104 +187,90 @@
-

Implementation

-

Max Kalika <max@gentoo.org> stated that he has a preliminary eclass that +

Implementation

+

Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that implements a good deal of this GLEP.

-

Stuart Herbert <stuart@gentoo.org> has committed:

+

Stuart Herbert <stuart at gentoo.org> has committed:

 webapp-apache.eclass
 

to CVS, this is a stop-gap measure whilst this GLEP is being finalised.

-

1. Web Server

-

A common default web server will have to be selected and ebuild authors should -ensure that their applications contain configuration directives suitable for -that server. Given the popularity of the Apache web server it is suggested -that Apache be selected as the Gentoo default web server.

-

Whilst it is acknowledged that other web servers do exist and are used, there -has to be an assumption made somewhere that people who choose to use something -other than the default have enough knowledge to adapt configurations -accordingly.

+

1. Web Server

+

A common default web server should be selected. Selection of a default web +server will help to reduce the number of bugs that are reported.

+

Given the popularity of the Apache web server it is suggested that Apache be +selected as the Gentoo default web server.

+

The Virtual Host Configuration tool (see below) will transparently support +different web servers, thus enabling web applications to be installed on a +Gentoo system irrespective of the installed web server.

-

1.1 Default Document Root

+

1.1 Default Document Root

+

The current default Document Root for Gentoo is /home/httpd/, this is +unsuitable for a couple of reasons:

+
+
    +
  • /home/ may be exported via nfs to numerous other hosts, it is not +acceptable to share publically accessible files with numerous hosts.
  • +
  • there is a potential (all be it small) for a user name clash
  • +
+

To ensure the greatest flexibility when installing applications the following Document Root locations are to be used:

  • For single host installations:

    -/var/www/localhost/htdocs/
    +/var/www/localhost/
     
  • -
  • For multiple virtual host installastions:

    +
  • For multiple virtual host installations:

    -/var/www/<fully qualified domain name>/htdocs/
    +/var/www/<fully qualified domain name>/
    +
     eg:
    -        /var/www/www.gentoo.org/htdocs/
    +        /var/www/www.gentoo.org/
     
+

Additionally the chosen location ( /var/www/ ) appears to be becoming a defacto +standard for Linux distributions.

-

1.2 Apache 2

-

All web application .ebuild will honour any USE flags that are intended to +

1.2 Apache 2

+

All web application .ebuilds will honour any USE flags that are intended to add support for Apache 2 as well as supporting Apache 1 installations.

-
-

2. Virtual Host Flexibility

-

In a similar vein to Gentoo's Zope scripts, namely zope-config, we -should be able to have multiple instances of a single web application -without duplicating all of the files.

-

This also allows system administrators to control where web applications -will appear on their system, as well as to customize a file in a single -instance of a web application without effecting the original material.

-

This is easily acheived thru use of Apache configuration directivies and -symlinks. For PHP instances, see http://tavi.sourceforge.net/VirtualHosts -for some details.

-

The primary idea here is that to the web-application, it appears that -all of it's configuration and files are in the instance directory, but -the files are physicalled located elsewhere.

-
-

2.1 New "vhost" USE Flag

-

To enable support for multiple virtual host installations a new USE flag is -to be added to Portage. The use flag will be:

-
-vhost
-
-

When vhost is _set_ the installation location and configuration for the web -application will be effected, see below for more details.

-
-
-

2.2 VHost Configuration Tool

-

To assist administration of multiple virtual hosts a "VHost Configuration Tool" -needs to be developed and implemented. Initial discussion and regarding the VHost -Config tool can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.

-

The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo. -Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).

-

<< TO BE EXPANDED UPON >>

-
-
-
-

3. Application Installation Location

+
+

2. Application Installation

The current accepted standard Document Root in Gentoo is /home/httpd. The discussion suggest that this is not the best location to install web based applications.

+
+

2.1 Application SLOTs

+

All ebuilds are to set the SLOT variable as follows:

+
+SLOT="${PV}"
+
+

Setting the SLOT variable as shown will enable different versions of the same +web application to be served concurrently by one server.

+
+
+

2.2 Installation Paths

Web applications should be installed outside of the Document Root using the following defaults:

  • for files to be served to clients:

    -/usr/share/webapps/${PF}/
    -
    -/usr/share/webapps/${PF}/public_html/ for files served by the web server
    +/usr/share/webapps/${PF}/htdocs/
     
    -/usr/share/webapps/${PF}/cgi-bin/ for CGI-BIN files
    +/usr/share/webapps/${PF}/cgi-bin/
     
  • -
  • install configuration files in:

    +
  • install site default configuration files in:

     /etc/webapps/${PF}/
     
    @@ -297,42 +282,78 @@
+
+
+
+

3. Virtual Host Support

+

The ability to easily configure and administer multiple virtual hosts is a +must.

+
+

3.1 New "vhost" USE Flag

+

To enable support for multiple virtual host installations a new USE flag is +to be added to Portage. The use flag will be:

+
+vhost
+
+

When vhost is _set_ the installation location and configuration for the web +application will be effected, see below for more details.

+
+
+

3.2 VHost Configuration Tool

+

To assist administration of multiple virtual hosts a "VHost Configuration Tool" +needs to be developed and implemented. Initial discussion regarding the VHost +Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.

+

It's the job of the VHost Config toolset to make a local instance of the web +application run under a specific web server.

+

The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo. +Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).

+

Bug #26293 [4] will be used to track the initial progress of the VHost +Configuration Tool.

+

The vhost-config must do three main things:

+
+
    +
  • creates directories (copies a skeleton directory for the most part).
  • +
  • create web server vhost config files.
  • +
  • HUP web server so it reads in the new config without stopping.
  • +
+
+

Initially the VHost Config tool should provide support for the Apache web +server. As the tool matures support for other web servers can be added.

+
-

3.1 Single Host Installation

+

4.1 Single Host Installation

For single host installations the .ebuild will make the required configurations changes and symlinks using the VHost Config tool to ensure that the web application is available to be served from:

-/var/www/localhost/htdocs/${PN}
+/var/www/localhost/htdocs/${PF}/
 
+

In this case it may be feasible for the VHost Config tool to simply symlink the +directories from /usr/share/webapps/${PF}/ as is appropriate.

-

3.2 Virtual Host Installation

+

4.2 Virtual Host Installation

For installations that support multiple virtual hosts the .ebuild will install the web application into the default location and then leave configuration to the user through the VHost Config tool.

-

<< TO BE EXPANDED UPON >>

+

In this case the web application files will be copied from +/usr/share/webapps/${PF}/ to /var/www/<FQDN>/ by the VHost Config tool.

-
-
-

4. Application Configuration

-

Having application configuration files in the Document Root of a web -server is a potential security risk. Additionally given the way that many -ebuilds currently install web applications it can also lead to the -overwriting of important configuration files.

-

As stated above web application configuration files are to be installed into:

+
+

4.3 Configuration Files

+

As stated above web application site default configuration files are to be +installed into:

 /etc/webapps/${PF}/
 
-

By installing application configuration files in /etc Portage CONFIG_PROTECT -features can be used to ensure that configuration files are not overwritten.

-
-

4.1 Virtual Host Support

-

<< TO BE EXPANDED UPON >>

+

The files in this directory are then copied (not symlinked!) by the VHost +Config tool to the Document Root for each instance of the app that is installed.

+

This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT +behaviour for the web applications.

-

5. Application Permissions

+

5. Application Permissions

Installing web applications and giving the web server ownership of the files is a security risk. This can possibly lead to application configuration files being accessed by unwanted third parties.

@@ -342,7 +363,7 @@
-

Backwards Compatibility

+

Backwards Compatibility

There may be some issues regarding compatibility with existing installs of web applications. This is particularly true if the default Document Root is moved from what is accepted as the current standard (/home/httpd).

@@ -353,14 +374,14 @@ /etc/webapps/${PF}/ directory.
  • modification/reconfiguration of applications so that they are aware of the location of configuration files.
  • -
  • creating approriate Apache configuration snippets for inclusion -in the Apache configuration files.
  • +
  • creating the VHost Config toolset to enable installation and +configuration of web applications irrespective of web server.
  • @@ -389,7 +416,7 @@