en/glep/glep-0011.txt

GLEP: 11
Title: Web Application Installation
Version: $Revision: 1.4 $
Last-Modified: $Date: 2003/08/13 13:45:38 $
Author: Troy Dack <tad@gentoo.org>
Author: Stuart Herbert <stuart@gentoo.org>
Discussions-To: gentoo-dev@gentoo.org
Status: Accepted
Type: Standards Track
Content-Type: text/x-rst
Created: 02-August-2003
Post-History: 07-Aug-2003, 12-Aug-2003, 13-Aug-2003

Credits
=======

Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
[#WebAppPost2]_ [#WebAppPost3]_ by:

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

Definitions
===========

        *Web Application*
                an application that requires a web server to function and interacts with
                the user via a browser

        *Web Application Instance*
                An apparent install of the Web Application that is served up via the
                webserver. There may be any number of instances per Web Application.
                This is a major use for web applications. Our Gentoo Zope setup
                already provides instances and can be used for some concepts on this
                matter.

        *Web Application Setup Program*
                A script similar in function to zope-config that sets up instances.

        *Document Root*
                a location in the file system that forms the main document tree visible from
                the web

Conventions
===========

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

                /foo/bar/

        When describing the location of a specific file (irrespective of any
        file extention) it will shown *with out* a trailing slash, eg::

                /foo/blah

Abstract
========

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

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:

        * where the application should be installed
        * what user and permissions the application should be given
        * where any configuration files related to the application should be
          installed.

Due to a lack of standard install method configuration files are at
risk of being overwritten during upgrade, potentially causing system
administrators down tine as they have to reconfigure web applications
after an upgrade.

Rationale
=========

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

        1. Gentoo installed web applications (eg: horde, phpbb, cacti,
           phpmysql) should not be installed in the Document Root of a web server.
        2. Web applications should not have their configuration files installed
           under the Document Root of a web server.

                i. Web Application must be slotted by their full version numbers to
                   further avoid downtime when true configuration changes are required.

        3. Web applications should not be owned by the same user as the web server.
        4. It should be easily possible to have multiple instances of a web
           application without any duplication of source files.
        5. It should be immediately apparent how to control instances of a web
           application.

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 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 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
'''''''''''''''''''''''''

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/

        * For multiple virtual host installations::

                /var/www/<fully qualified domain name>/

                eg:
                        /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 .ebuilds will honour any USE flags that are intended to
add support for Apache 2 as well as supporting Apache 1 installations.

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}/htdocs/

                /usr/share/webapps/${PF}/cgi-bin/

        * install *site default* configuration files in::

                /etc/webapps/${PF}/

        * for documentation files (not served to clients)::

                /usr/share/doc/${PF}/

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.

Web Server .ebuilds will require the VHost Config tool as a dependency (DEPEND).

`Bug #26293`_ will be used to track the initial progress of the VHost
Configuration Tool.

.. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293


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.3 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/${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.4 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.

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

3.5 Configuration Files
'''''''''''''''''''''''

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

        /etc/webapps/${PF}/

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.

4. 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.

All web applications should be owned by *root* unless the application
absolutely requires write access to its installation directories at execution
time.

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).

The main issues are:
        * transition of existing configuration files to the
          /etc/webapps/${PF}/ directory.
        * modification/reconfiguration of applications so that they
          are aware of the location of configuration files.
        * creating the VHost Config toolset to enable installation and
          configuration of web applications irrespective of web server.


References
==========

.. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
.. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
.. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E

Copyright
=========

This document has been placed in the public domain.
1	g2boojum	1.1	GLEP: 11
2			Title: Web Application Installation
3	g2boojum	1.5	Version: $Revision: 1.4 $
4			Last-Modified: $Date: 2003/08/13 13:45:38 $
5	robbat2	1.3	Author: Troy Dack <tad@gentoo.org>
6	g2boojum	1.5	Author: Stuart Herbert <stuart@gentoo.org>
7	g2boojum	1.1	Discussions-To: gentoo-dev@gentoo.org
8	g2boojum	1.5	Status: Accepted
9	g2boojum	1.1	Type: Standards Track
10			Content-Type: text/x-rst
11	g2boojum	1.4	Created: 02-August-2003
12			Post-History: 07-Aug-2003, 12-Aug-2003, 13-Aug-2003
13	g2boojum	1.1
14			Credits
15			=======
16
17			Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
18			[#WebAppPost2]_ [#WebAppPost3]_ by:
19
20	g2boojum	1.2	Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>,
21			Robin H.Johnson <robbat2 at gentoo.org> and others
22	g2boojum	1.1
23			Definitions
24			===========
25
26			Web Application
27			an application that requires a web server to function and interacts with
28			the user via a browser
29
30			Web Application Instance
31			An apparent install of the Web Application that is served up via the
32			webserver. There may be any number of instances per Web Application.
33			This is a major use for web applications. Our Gentoo Zope setup
34			already provides instances and can be used for some concepts on this
35			matter.
36
37			Web Application Setup Program
38			A script similar in function to zope-config that sets up instances.
39
40			Document Root
41			a location in the file system that forms the main document tree visible from
42			the web
43
44			Conventions
45			===========
46
47			When describing the location of a directory in the file system it
48			wil be shown with a trailing slash, eg::
49
50			/foo/bar/
51
52			When describing the location of a specific file (irrespective of any
53			file extention) it will shown with out a trailing slash, eg::
54
55			/foo/blah
56
57			Abstract
58			========
59
60			To define where and how web based applications should be installed by Gentoo.
61
62			Motivation
63			==========
64
65			Currently there is no standard defined regarding the installation of web
66			based applicaitons in Gentoo. This leads to ebuild authors creating a
67			variety of methods to determine:
68
69			* where the application should be installed
70			* what user and permissions the application should be given
71			* where any configuration files related to the application should be
72			installed.
73
74			Due to a lack of standard install method configuration files are at
75			risk of being overwritten during upgrade, potentially causing system
76			administrators down tine as they have to reconfigure web applications
77			after an upgrade.
78
79			Rationale
80			=========
81
82			A discussion on the gentoo-dev mailing list [#WebAppPost1]_ raised the
83			following points regarding how Gentoo handles the installation of web based
84			applications:
85
86			1. Gentoo installed web applications (eg: horde, phpbb, cacti,
87			phpmysql) should not be installed in the Document Root of a web server.
88			2. Web applications should not have their configuration files installed
89			under the Document Root of a web server.
90
91	g2boojum	1.2	i. Web Application must be slotted by their full version numbers to
92	g2boojum	1.1	further avoid downtime when true configuration changes are required.
93
94			3. Web applications should not be owned by the same user as the web server.
95			4. It should be easily possible to have multiple instances of a web
96			application without any duplication of source files.
97			5. It should be immediately apparent how to control instances of a web
98			application.
99
100			Implementation
101			==============
102
103	g2boojum	1.2	Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that
104	g2boojum	1.1	implements a good deal of this GLEP.
105
106	g2boojum	1.2	Stuart Herbert <stuart at gentoo.org> has committed::
107	g2boojum	1.1
108			webapp-apache.eclass
109
110			to CVS, this is a stop-gap measure whilst this GLEP is being finalised.
111
112
113			1. Web Server
114	g2boojum	1.2	-------------
115	g2boojum	1.1
116	g2boojum	1.2	A common default web server should be selected. Selection of a default web
117			server will help to reduce the number of bugs that are reported.
118
119			Given the popularity of the Apache web server it is suggested that Apache be
120			selected as the Gentoo default web server.
121
122			The Virtual Host Configuration tool (see below) will transparently support
123			different web servers, thus enabling web applications to be installed on a
124			Gentoo system irrespective of the installed web server.
125	g2boojum	1.1
126			1.1 Default Document Root
127			'''''''''''''''''''''''''
128
129	g2boojum	1.2	The current default Document Root for Gentoo is /home/httpd/, this is
130			unsuitable for a couple of reasons:
131
132			* /home/ may be exported via nfs to numerous other hosts, it is not
133			acceptable to share publically accessible files with numerous hosts.
134
135			* there is a potential (all be it small) for a user name clash
136
137	g2boojum	1.1	To ensure the greatest flexibility when installing applications the following
138			Document Root locations are to be used:
139
140			* For single host installations::
141
142	g2boojum	1.2	/var/www/localhost/
143
144			* For multiple virtual host installations::
145	g2boojum	1.1
146	g2boojum	1.2	/var/www/<fully qualified domain name>/
147	g2boojum	1.1
148			eg:
149	g2boojum	1.2	/var/www/www.gentoo.org/
150
151			Additionally the chosen location ( /var/www/ ) appears to be becoming a defacto
152			standard for Linux distributions.
153	g2boojum	1.1
154			1.2 Apache 2
155	g2boojum	1.2	''''''''''''
156	g2boojum	1.1
157	g2boojum	1.2	All web application .ebuilds will honour any USE flags that are intended to
158	g2boojum	1.1	add support for Apache 2 as well as supporting Apache 1 installations.
159
160	g2boojum	1.2	2. Application Installation
161			---------------------------
162
163			The current accepted standard Document Root in Gentoo is /home/httpd. The
164			discussion suggest that this is not the best location to install web based
165			applications.
166
167			2.1 Application SLOTs
168			'''''''''''''''''''''
169	g2boojum	1.1
170	g2boojum	1.2	All ebuilds are to set the SLOT variable as follows::
171
172			SLOT="${PV}"
173
174			Setting the SLOT variable as shown will enable different versions of the same
175			web application to be served concurrently by one server.
176
177			2.2 Installation Paths
178			''''''''''''''''''''''
179
180			Web applications should be installed outside of the Document Root using the following
181			defaults:
182
183			* for files to be served to clients::
184
185			/usr/share/webapps/${PF}/htdocs/
186
187			/usr/share/webapps/${PF}/cgi-bin/
188
189			* install site default configuration files in::
190
191			/etc/webapps/${PF}/
192
193			* for documentation files (not served to clients)::
194
195			/usr/share/doc/${PF}/
196
197			3. Virtual Host Support
198			-----------------------
199	g2boojum	1.1
200	g2boojum	1.2	The ability to easily configure and administer multiple virtual hosts is a
201			must.
202	g2boojum	1.1
203	g2boojum	1.2	3.1 New "vhost" USE Flag
204	g2boojum	1.1	''''''''''''''''''''''''
205
206			To enable support for multiple virtual host installations a new USE flag is
207			to be added to Portage. The use flag will be::
208
209			vhost
210
211			When vhost is _set_ the installation location and configuration for the web
212			application will be effected, see below for more details.
213
214	g2boojum	1.2	3.2 VHost Configuration Tool
215	g2boojum	1.1	''''''''''''''''''''''''''''
216
217			To assist administration of multiple virtual hosts a "VHost Configuration Tool"
218	robbat2	1.3	needs to be developed and implemented. Initial discussion regarding the VHost
219	g2boojum	1.2	Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
220
221	robbat2	1.3	It's the job of the VHost Config toolset to make a local instance of the web
222	g2boojum	1.2	application run under a specific web server.
223	g2boojum	1.1
224			The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
225	robbat2	1.3
226			Web Server .ebuilds will require the VHost Config tool as a dependency (DEPEND).
227	g2boojum	1.1
228	g2boojum	1.2	`Bug #26293`_ will be used to track the initial progress of the VHost
229			Configuration Tool.
230	g2boojum	1.1
231	g2boojum	1.2	.. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
232	g2boojum	1.1
233
234	g2boojum	1.2	The vhost-config must do three main things:
235	g2boojum	1.1
236	g2boojum	1.2	- creates directories (copies a skeleton directory for the most part).
237			- create web server vhost config files.
238			- HUP web server so it reads in the new config without stopping.
239	g2boojum	1.1
240	g2boojum	1.2	Initially the VHost Config tool should provide support for the Apache web
241			server. As the tool matures support for other web servers can be added.
242	g2boojum	1.1
243	robbat2	1.3	3.3 Single Host Installation
244	g2boojum	1.1	''''''''''''''''''''''''''''
245
246			For single host installations the .ebuild will make the required
247			configurations changes and symlinks using the VHost Config tool to ensure
248			that the web application is available to be served from::
249
250	g2boojum	1.2	/var/www/localhost/htdocs/${PF}/
251
252			In this case it may be feasible for the VHost Config tool to simply symlink the
253			directories from /usr/share/webapps/${PF}/ as is appropriate.
254	g2boojum	1.1
255	robbat2	1.3	3.4 Virtual Host Installation
256	g2boojum	1.1	'''''''''''''''''''''''''''''
257
258			For installations that support multiple virtual hosts the .ebuild will
259			install the web application into the default location and then leave configuration
260			to the user through the VHost Config tool.
261
262	g2boojum	1.2	In this case the web application files will be copied from
263			/usr/share/webapps/${PF}/ to /var/www/<FQDN>/ by the VHost Config tool.
264	g2boojum	1.1
265	robbat2	1.3	3.5 Configuration Files
266	g2boojum	1.2	'''''''''''''''''''''''
267	g2boojum	1.1
268	robbat2	1.3	As stated above web application site default configuration files are to be
269	g2boojum	1.2	installed into::
270	g2boojum	1.1
271			/etc/webapps/${PF}/
272
273	g2boojum	1.2	The files in this directory are then copied (not symlinked!) by the VHost
274			Config tool to the Document Root for each instance of the app that is installed.
275	g2boojum	1.1
276	robbat2	1.3	This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
277	g2boojum	1.2	behaviour for the web applications.
278	g2boojum	1.1
279	robbat2	1.3	4. Application Permissions
280	g2boojum	1.1	--------------------------
281
282			Installing web applications and giving the web server ownership of the files
283			is a security risk. This can possibly lead to application configuration
284			files being accessed by unwanted third parties.
285
286			All web applications should be owned by root unless the application
287			absolutely requires write access to its installation directories at execution
288			time.
289
290			Backwards Compatibility
291			=======================
292
293			There may be some issues regarding compatibility with existing installs of
294			web applications. This is particularly true if the default Document Root is
295			moved from what is accepted as the current standard (/home/httpd).
296
297			The main issues are:
298			* transition of existing configuration files to the
299			/etc/webapps/${PF}/ directory.
300			* modification/reconfiguration of applications so that they
301			are aware of the location of configuration files.
302	g2boojum	1.2	* creating the VHost Config toolset to enable installation and
303			configuration of web applications irrespective of web server.
304	g2boojum	1.1
305
306			References
307			==========
308
309			.. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
310			.. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
311			.. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E
312
313			Copyright
314			=========
315
316			This document has been placed in the public domain.