/[gentoo]/xml/htdocs/proj/en/glep/glep-0011.txt
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0011.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download)
Thu Aug 7 19:02:40 2003 UTC (11 years, 2 months ago) by g2boojum
Branch: MAIN
File MIME type: text/plain
initial import

1 g2boojum 1.1 GLEP: 11
2     Title: Web Application Installation
3     Version: $Revision: 1.1 $
4     Last-Modified: $Date: 2003/08/07 10: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    
13     Credits
14     =======
15    
16     Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
17     [#WebAppPost2]_ [#WebAppPost3]_ by:
18    
19     Stuart Herbert <stuart@gentoo.org>, Max Kalika <max@gentoo.org>,
20     Robin H.Johnson <robbat2@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 major 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@gentoo.org> stated that he has a preliminary eclass that
103     implements a good deal of this GLEP.
104    
105     Stuart Herbert <stuart@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 will have to be selected and ebuild authors should
116     ensure that their applications contain configuration directives suitable for
117     that server. Given the popularity of the Apache web server it is suggested
118     that Apache be selected as the Gentoo default web server.
119    
120     Whilst it is acknowledged that other web servers do exist and are used, there
121     has to be an assumption made somewhere that people who choose to use something
122     other than the default have enough knowledge to adapt configurations
123     accordingly.
124    
125     1.1 Default Document Root
126     '''''''''''''''''''''''''
127    
128     To ensure the greatest flexibility when installing applications the following
129     *Document Root* locations are to be used:
130    
131     * For single host installations::
132    
133     /var/www/localhost/htdocs/
134    
135     * For multiple virtual host installastions::
136    
137     /var/www/<fully qualified domain name>/htdocs/
138     eg:
139     /var/www/www.gentoo.org/htdocs/
140    
141     1.2 Apache 2
142     ''''''''''''''''''''''''
143    
144     All web application .ebuild will honour any USE flags that are intended to
145     add support for Apache 2 as well as supporting Apache 1 installations.
146    
147    
148     2. Virtual Host Flexibility
149     ---------------------------
150    
151     In a similar vein to Gentoo's Zope scripts, namely zope-config, we
152     should be able to have multiple instances of a single web application
153     without duplicating all of the files.
154    
155     This also allows system administrators to control where web applications
156     will appear on their system, as well as to customize a file in a single
157     instance of a web application without effecting the original material.
158    
159     This is easily acheived thru use of Apache configuration directivies and
160     symlinks. For PHP instances, see http://tavi.sourceforge.net/VirtualHosts
161     for some details.
162    
163     The primary idea here is that to the web-application, it appears that
164     all of it's configuration and files are in the instance directory, but
165     the files are physicalled located elsewhere.
166    
167     2.1 New "vhost" USE Flag
168     ''''''''''''''''''''''''
169    
170     To enable support for multiple virtual host installations a new USE flag is
171     to be added to Portage. The use flag will be::
172    
173     vhost
174    
175     When *vhost* is _set_ the installation location and configuration for the web
176     application will be effected, see below for more details.
177    
178     2.2 VHost Configuration Tool
179     ''''''''''''''''''''''''''''
180    
181     To assist administration of multiple virtual hosts a "VHost Configuration Tool"
182     needs to be developed and implemented. Initial discussion and regarding the VHost
183     Config tool can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
184    
185     The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
186     Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).
187    
188     << TO BE EXPANDED UPON >>
189    
190     3. Application Installation Location
191     ------------------------------------
192    
193     The current accepted standard Document Root in Gentoo is /home/httpd. The
194     discussion suggest that this is not the best location to install web based
195     applications.
196    
197     Web applications should be installed outside of the Document Root using the following
198     defaults:
199    
200     * for files to be served to clients::
201    
202     /usr/share/webapps/${PF}/
203    
204     /usr/share/webapps/${PF}/public_html/ for files served by the web server
205    
206     /usr/share/webapps/${PF}/cgi-bin/ for CGI-BIN files
207    
208     * install configuration files in::
209    
210     /etc/webapps/${PF}/
211    
212     * for documentation files (not served to clients)::
213    
214     /usr/share/doc/${PF}/
215    
216     3.1 Single Host Installation
217     ''''''''''''''''''''''''''''
218    
219     For single host installations the .ebuild will make the required
220     configurations changes and symlinks using the VHost Config tool to ensure
221     that the web application is available to be served from::
222    
223     /var/www/localhost/htdocs/${PN}
224    
225     3.2 Virtual Host Installation
226     '''''''''''''''''''''''''''''
227    
228     For installations that support multiple virtual hosts the .ebuild will
229     install the web application into the default location and then leave configuration
230     to the user through the VHost Config tool.
231    
232     << TO BE EXPANDED UPON >>
233    
234     4. Application Configuration
235     ----------------------------
236    
237     Having application configuration files in the Document Root of a web
238     server is a potential security risk. Additionally given the way that many
239     ebuilds currently install web applications it can also lead to the
240     overwriting of important configuration files.
241    
242     As stated above web application configuration files are to be installed into::
243    
244     /etc/webapps/${PF}/
245    
246     By installing application configuration files in /etc Portage CONFIG_PROTECT
247     features can be used to ensure that configuration files are not overwritten.
248    
249     4.1 Virtual Host Support
250     ''''''''''''''''''''''''
251    
252     << TO BE EXPANDED UPON >>
253    
254     5. Application Permissions
255     --------------------------
256    
257     Installing web applications and giving the web server ownership of the files
258     is a security risk. This can possibly lead to application configuration
259     files being accessed by unwanted third parties.
260    
261     All web applications should be owned by *root* unless the application
262     absolutely requires write access to its installation directories at execution
263     time.
264    
265     Backwards Compatibility
266     =======================
267    
268     There may be some issues regarding compatibility with existing installs of
269     web applications. This is particularly true if the default Document Root is
270     moved from what is accepted as the current standard (/home/httpd).
271    
272     The main issues are:
273     * transition of existing configuration files to the
274     /etc/webapps/${PF}/ directory.
275     * modification/reconfiguration of applications so that they
276     are aware of the location of configuration files.
277     * creating approriate Apache configuration snippets for inclusion
278     in the Apache configuration files.
279    
280    
281     References
282     ==========
283    
284     .. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
285     .. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
286     .. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E
287    
288     Copyright
289     =========
290    
291     This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20