/[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.3 - (show annotations) (download)
Wed Aug 13 08:43:18 2003 UTC (10 years, 8 months ago) by robbat2
Branch: MAIN
Changes since 1.2: +13 -13 lines
File MIME type: text/plain
Commit for tad. Fixes numbering and changes one instance of 'Apache' to 'Web Server'

1 GLEP: 11
2 Title: Web Application Installation
3 Version: $Revision: 1.3 $
4 Last-Modified: $Date: 2003/08/13 17:02:43 $
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 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 at gentoo.org>, Max Kalika <max at gentoo.org>,
20 Robin H.Johnson <robbat2 at 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 full 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 at gentoo.org> stated that he has a preliminary eclass that
103 implements a good deal of this GLEP.
104
105 Stuart Herbert <stuart at 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 should be selected. Selection of a default web
116 server will help to reduce the number of bugs that are reported.
117
118 Given the popularity of the Apache web server it is suggested that Apache be
119 selected as the Gentoo default web server.
120
121 The Virtual Host Configuration tool (see below) will transparently support
122 different web servers, thus enabling web applications to be installed on a
123 Gentoo system irrespective of the installed web server.
124
125 1.1 Default Document Root
126 '''''''''''''''''''''''''
127
128 The current default Document Root for Gentoo is /home/httpd/, this is
129 unsuitable for a couple of reasons:
130
131 * /home/ may be exported via nfs to numerous other hosts, it is not
132 acceptable to share publically accessible files with numerous hosts.
133
134 * there is a potential (all be it small) for a user name clash
135
136 To ensure the greatest flexibility when installing applications the following
137 *Document Root* locations are to be used:
138
139 * For single host installations::
140
141 /var/www/localhost/
142
143 * For multiple virtual host installations::
144
145 /var/www/<fully qualified domain name>/
146
147 eg:
148 /var/www/www.gentoo.org/
149
150 Additionally the chosen location ( /var/www/ ) appears to be becoming a defacto
151 standard for Linux distributions.
152
153 1.2 Apache 2
154 ''''''''''''
155
156 All web application .ebuilds will honour any USE flags that are intended to
157 add support for Apache 2 as well as supporting Apache 1 installations.
158
159 2. Application Installation
160 ---------------------------
161
162 The current accepted standard Document Root in Gentoo is /home/httpd. The
163 discussion suggest that this is not the best location to install web based
164 applications.
165
166 2.1 Application SLOTs
167 '''''''''''''''''''''
168
169 All ebuilds are to set the SLOT variable as follows::
170
171 SLOT="${PV}"
172
173 Setting the SLOT variable as shown will enable different versions of the same
174 web application to be served concurrently by one server.
175
176 2.2 Installation Paths
177 ''''''''''''''''''''''
178
179 Web applications should be installed outside of the Document Root using the following
180 defaults:
181
182 * for files to be served to clients::
183
184 /usr/share/webapps/${PF}/htdocs/
185
186 /usr/share/webapps/${PF}/cgi-bin/
187
188 * install *site default* configuration files in::
189
190 /etc/webapps/${PF}/
191
192 * for documentation files (not served to clients)::
193
194 /usr/share/doc/${PF}/
195
196 3. Virtual Host Support
197 -----------------------
198
199 The ability to easily configure and administer multiple virtual hosts is a
200 must.
201
202 3.1 New "vhost" USE Flag
203 ''''''''''''''''''''''''
204
205 To enable support for multiple virtual host installations a new USE flag is
206 to be added to Portage. The use flag will be::
207
208 vhost
209
210 When *vhost* is _set_ the installation location and configuration for the web
211 application will be effected, see below for more details.
212
213 3.2 VHost Configuration Tool
214 ''''''''''''''''''''''''''''
215
216 To assist administration of multiple virtual hosts a "VHost Configuration Tool"
217 needs to be developed and implemented. Initial discussion regarding the VHost
218 Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
219
220 It's the job of the VHost Config toolset to make a local instance of the web
221 application run under a specific web server.
222
223 The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
224
225 Web Server .ebuilds will require the VHost Config tool as a dependency (DEPEND).
226
227 `Bug #26293`_ will be used to track the initial progress of the VHost
228 Configuration Tool.
229
230 .. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
231
232
233 The vhost-config must do three main things:
234
235 - creates directories (copies a skeleton directory for the most part).
236 - create web server vhost config files.
237 - HUP web server so it reads in the new config without stopping.
238
239 Initially the VHost Config tool should provide support for the Apache web
240 server. As the tool matures support for other web servers can be added.
241
242 3.3 Single Host Installation
243 ''''''''''''''''''''''''''''
244
245 For single host installations the .ebuild will make the required
246 configurations changes and symlinks using the VHost Config tool to ensure
247 that the web application is available to be served from::
248
249 /var/www/localhost/htdocs/${PF}/
250
251 In this case it may be feasible for the VHost Config tool to simply symlink the
252 directories from /usr/share/webapps/${PF}/ as is appropriate.
253
254 3.4 Virtual Host Installation
255 '''''''''''''''''''''''''''''
256
257 For installations that support multiple virtual hosts the .ebuild will
258 install the web application into the default location and then leave configuration
259 to the user through the VHost Config tool.
260
261 In this case the web application files will be copied from
262 /usr/share/webapps/${PF}/ to /var/www/<FQDN>/ by the VHost Config tool.
263
264 3.5 Configuration Files
265 '''''''''''''''''''''''
266
267 As stated above web application *site default* configuration files are to be
268 installed into::
269
270 /etc/webapps/${PF}/
271
272 The files in this directory are then copied (not symlinked!) by the VHost
273 Config tool to the Document Root for each instance of the app that is installed.
274
275 This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
276 behaviour for the web applications.
277
278 4. Application Permissions
279 --------------------------
280
281 Installing web applications and giving the web server ownership of the files
282 is a security risk. This can possibly lead to application configuration
283 files being accessed by unwanted third parties.
284
285 All web applications should be owned by *root* unless the application
286 absolutely requires write access to its installation directories at execution
287 time.
288
289 Backwards Compatibility
290 =======================
291
292 There may be some issues regarding compatibility with existing installs of
293 web applications. This is particularly true if the default Document Root is
294 moved from what is accepted as the current standard (/home/httpd).
295
296 The main issues are:
297 * transition of existing configuration files to the
298 /etc/webapps/${PF}/ directory.
299 * modification/reconfiguration of applications so that they
300 are aware of the location of configuration files.
301 * creating the VHost Config toolset to enable installation and
302 configuration of web applications irrespective of web server.
303
304
305 References
306 ==========
307
308 .. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
309 .. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
310 .. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E
311
312 Copyright
313 =========
314
315 This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20