en/glep/glep-0011.txt

GLEP: 11
Title: Web Application Installation
Version: $Revision: 1.2 $
Last-Modified: $Date: 2003/08/12 23:14:00 $
Author: Troy Dack <tad@gentoo.org>
Discussions-To: gentoo-dev@gentoo.org
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 02 August 2003
Post-History: 07 Aug 2003, 12 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.
Apache .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.

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

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.

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

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.

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