/[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 - (show 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 GLEP: 11
2 Title: Web Application Installation
3 Version: $Revision: 1.4 $
4 Last-Modified: $Date: 2003/08/13 13:45:38 $
5 Author: Troy Dack <tad@gentoo.org>
6 Author: Stuart Herbert <stuart@gentoo.org>
7 Discussions-To: gentoo-dev@gentoo.org
8 Status: Accepted
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
13
14 Credits
15 =======
16
17 Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
18 [#WebAppPost2]_ [#WebAppPost3]_ by:
19
20 Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>,
21 Robin H.Johnson <robbat2 at gentoo.org> and others
22
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 i. Web Application must be slotted by their full version numbers to
92 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 Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that
104 implements a good deal of this GLEP.
105
106 Stuart Herbert <stuart at gentoo.org> has committed::
107
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 -------------
115
116 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
126 1.1 Default Document Root
127 '''''''''''''''''''''''''
128
129 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 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 /var/www/localhost/
143
144 * For multiple virtual host installations::
145
146 /var/www/<fully qualified domain name>/
147
148 eg:
149 /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
154 1.2 Apache 2
155 ''''''''''''
156
157 All web application .ebuilds will honour any USE flags that are intended to
158 add support for Apache 2 as well as supporting Apache 1 installations.
159
160 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
170 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
200 The ability to easily configure and administer multiple virtual hosts is a
201 must.
202
203 3.1 New "vhost" USE Flag
204 ''''''''''''''''''''''''
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 3.2 VHost Configuration Tool
215 ''''''''''''''''''''''''''''
216
217 To assist administration of multiple virtual hosts a "VHost Configuration Tool"
218 needs to be developed and implemented. Initial discussion regarding the VHost
219 Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
220
221 It's the job of the VHost Config toolset to make a local instance of the web
222 application run under a specific web server.
223
224 The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
225
226 Web Server .ebuilds will require the VHost Config tool as a dependency (DEPEND).
227
228 `Bug #26293`_ will be used to track the initial progress of the VHost
229 Configuration Tool.
230
231 .. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
232
233
234 The vhost-config must do three main things:
235
236 - 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
240 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
243 3.3 Single Host Installation
244 ''''''''''''''''''''''''''''
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 /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
255 3.4 Virtual Host Installation
256 '''''''''''''''''''''''''''''
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 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
265 3.5 Configuration Files
266 '''''''''''''''''''''''
267
268 As stated above web application *site default* configuration files are to be
269 installed into::
270
271 /etc/webapps/${PF}/
272
273 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
276 This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
277 behaviour for the web applications.
278
279 4. Application Permissions
280 --------------------------
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 * creating the VHost Config toolset to enable installation and
303 configuration of web applications irrespective of web server.
304
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