/[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.5 - (hide annotations) (download)
Sat Jan 31 21:56:55 2004 UTC (10 years, 8 months ago) by g2boojum
Branch: MAIN
Changes since 1.4: +4 -3 lines
File MIME type: text/plain
Minor fixes

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.

  ViewVC Help
Powered by ViewVC 1.1.20