/[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.1 - (show annotations) (download)
Thu Aug 7 19:02:40 2003 UTC (11 years ago) by g2boojum
Branch: MAIN
File MIME type: text/plain
initial import

1 GLEP: 11
2 Title: Web Application Installation
3 Version: $Revision: 1.1 $
4 Last-Modified: $Date: 2003/08/07 10:00 $
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
13 Credits
14 =======
15
16 Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
17 [#WebAppPost2]_ [#WebAppPost3]_ by:
18
19 Stuart Herbert <stuart@gentoo.org>, Max Kalika <max@gentoo.org>,
20 Robin H.Johnson <robbat2@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 major 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@gentoo.org> stated that he has a preliminary eclass that
103 implements a good deal of this GLEP.
104
105 Stuart Herbert <stuart@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 will have to be selected and ebuild authors should
116 ensure that their applications contain configuration directives suitable for
117 that server. Given the popularity of the Apache web server it is suggested
118 that Apache be selected as the Gentoo default web server.
119
120 Whilst it is acknowledged that other web servers do exist and are used, there
121 has to be an assumption made somewhere that people who choose to use something
122 other than the default have enough knowledge to adapt configurations
123 accordingly.
124
125 1.1 Default Document Root
126 '''''''''''''''''''''''''
127
128 To ensure the greatest flexibility when installing applications the following
129 *Document Root* locations are to be used:
130
131 * For single host installations::
132
133 /var/www/localhost/htdocs/
134
135 * For multiple virtual host installastions::
136
137 /var/www/<fully qualified domain name>/htdocs/
138 eg:
139 /var/www/www.gentoo.org/htdocs/
140
141 1.2 Apache 2
142 ''''''''''''''''''''''''
143
144 All web application .ebuild will honour any USE flags that are intended to
145 add support for Apache 2 as well as supporting Apache 1 installations.
146
147
148 2. Virtual Host Flexibility
149 ---------------------------
150
151 In a similar vein to Gentoo's Zope scripts, namely zope-config, we
152 should be able to have multiple instances of a single web application
153 without duplicating all of the files.
154
155 This also allows system administrators to control where web applications
156 will appear on their system, as well as to customize a file in a single
157 instance of a web application without effecting the original material.
158
159 This is easily acheived thru use of Apache configuration directivies and
160 symlinks. For PHP instances, see http://tavi.sourceforge.net/VirtualHosts
161 for some details.
162
163 The primary idea here is that to the web-application, it appears that
164 all of it's configuration and files are in the instance directory, but
165 the files are physicalled located elsewhere.
166
167 2.1 New "vhost" USE Flag
168 ''''''''''''''''''''''''
169
170 To enable support for multiple virtual host installations a new USE flag is
171 to be added to Portage. The use flag will be::
172
173 vhost
174
175 When *vhost* is _set_ the installation location and configuration for the web
176 application will be effected, see below for more details.
177
178 2.2 VHost Configuration Tool
179 ''''''''''''''''''''''''''''
180
181 To assist administration of multiple virtual hosts a "VHost Configuration Tool"
182 needs to be developed and implemented. Initial discussion and regarding the VHost
183 Config tool can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
184
185 The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
186 Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).
187
188 << TO BE EXPANDED UPON >>
189
190 3. Application Installation Location
191 ------------------------------------
192
193 The current accepted standard Document Root in Gentoo is /home/httpd. The
194 discussion suggest that this is not the best location to install web based
195 applications.
196
197 Web applications should be installed outside of the Document Root using the following
198 defaults:
199
200 * for files to be served to clients::
201
202 /usr/share/webapps/${PF}/
203
204 /usr/share/webapps/${PF}/public_html/ for files served by the web server
205
206 /usr/share/webapps/${PF}/cgi-bin/ for CGI-BIN files
207
208 * install configuration files in::
209
210 /etc/webapps/${PF}/
211
212 * for documentation files (not served to clients)::
213
214 /usr/share/doc/${PF}/
215
216 3.1 Single Host Installation
217 ''''''''''''''''''''''''''''
218
219 For single host installations the .ebuild will make the required
220 configurations changes and symlinks using the VHost Config tool to ensure
221 that the web application is available to be served from::
222
223 /var/www/localhost/htdocs/${PN}
224
225 3.2 Virtual Host Installation
226 '''''''''''''''''''''''''''''
227
228 For installations that support multiple virtual hosts the .ebuild will
229 install the web application into the default location and then leave configuration
230 to the user through the VHost Config tool.
231
232 << TO BE EXPANDED UPON >>
233
234 4. Application Configuration
235 ----------------------------
236
237 Having application configuration files in the Document Root of a web
238 server is a potential security risk. Additionally given the way that many
239 ebuilds currently install web applications it can also lead to the
240 overwriting of important configuration files.
241
242 As stated above web application configuration files are to be installed into::
243
244 /etc/webapps/${PF}/
245
246 By installing application configuration files in /etc Portage CONFIG_PROTECT
247 features can be used to ensure that configuration files are not overwritten.
248
249 4.1 Virtual Host Support
250 ''''''''''''''''''''''''
251
252 << TO BE EXPANDED UPON >>
253
254 5. Application Permissions
255 --------------------------
256
257 Installing web applications and giving the web server ownership of the files
258 is a security risk. This can possibly lead to application configuration
259 files being accessed by unwanted third parties.
260
261 All web applications should be owned by *root* unless the application
262 absolutely requires write access to its installation directories at execution
263 time.
264
265 Backwards Compatibility
266 =======================
267
268 There may be some issues regarding compatibility with existing installs of
269 web applications. This is particularly true if the default Document Root is
270 moved from what is accepted as the current standard (/home/httpd).
271
272 The main issues are:
273 * transition of existing configuration files to the
274 /etc/webapps/${PF}/ directory.
275 * modification/reconfiguration of applications so that they
276 are aware of the location of configuration files.
277 * creating approriate Apache configuration snippets for inclusion
278 in the Apache configuration files.
279
280
281 References
282 ==========
283
284 .. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
285 .. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
286 .. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E
287
288 Copyright
289 =========
290
291 This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20