/[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 - (show 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 GLEP: 11
2 Title: Web Application Installation
3 Version: $Revision: 1.5 $
4 Last-Modified: $Date: 2004/01/31 21:56:55 $
5 Author: Troy Dack <tad@gentoo.org>
6 Author: Stuart Herbert <stuart@gentoo.org>
7 Discussions-To: gentoo-dev@gentoo.org
8 Status: Final
9 Type: Standards Track
10 Content-Type: text/x-rst
11 Created: 02-August-2003
12 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
19 Credits
20 =======
21
22 Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
23 [#WebAppPost2]_ [#WebAppPost3]_ by:
24
25 Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>,
26 Robin H.Johnson <robbat2 at gentoo.org> and others
27
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 i. Web Application must be slotted by their full version numbers to
97 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 Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that
109 implements a good deal of this GLEP.
110
111 Stuart Herbert <stuart at gentoo.org> has committed::
112
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 -------------
120
121 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
131 1.1 Default Document Root
132 '''''''''''''''''''''''''
133
134 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 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 /var/www/localhost/
148
149 * For multiple virtual host installations::
150
151 /var/www/<fully qualified domain name>/
152
153 eg:
154 /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
159 1.2 Apache 2
160 ''''''''''''
161
162 All web application .ebuilds will honour any USE flags that are intended to
163 add support for Apache 2 as well as supporting Apache 1 installations.
164
165 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
175 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
205 The ability to easily configure and administer multiple virtual hosts is a
206 must.
207
208 3.1 New "vhost" USE Flag
209 ''''''''''''''''''''''''
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 3.2 VHost Configuration Tool
220 ''''''''''''''''''''''''''''
221
222 To assist administration of multiple virtual hosts a "VHost Configuration Tool"
223 needs to be developed and implemented. Initial discussion regarding the VHost
224 Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
225
226 It's the job of the VHost Config toolset to make a local instance of the web
227 application run under a specific web server.
228
229 The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
230
231 Web Server .ebuilds will require the VHost Config tool as a dependency (DEPEND).
232
233 `Bug #26293`_ will be used to track the initial progress of the VHost
234 Configuration Tool.
235
236 .. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
237
238
239 The vhost-config must do three main things:
240
241 - 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
245 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
248 3.3 Single Host Installation
249 ''''''''''''''''''''''''''''
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 /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
260 3.4 Virtual Host Installation
261 '''''''''''''''''''''''''''''
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 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
270 3.5 Configuration Files
271 '''''''''''''''''''''''
272
273 As stated above web application *site default* configuration files are to be
274 installed into::
275
276 /etc/webapps/${PF}/
277
278 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
281 This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
282 behaviour for the web applications.
283
284 4. Application Permissions
285 --------------------------
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 * creating the VHost Config toolset to enable installation and
308 configuration of web applications irrespective of web server.
309
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