/[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.6 - (hide annotations) (download)
Mon Sep 4 03:12:43 2006 UTC (7 years, 11 months ago) by g2boojum
Branch: MAIN
CVS Tags: HEAD
Changes since 1.5: +9 -4 lines
File MIME type: text/plain
update

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

  ViewVC Help
Powered by ViewVC 1.1.20