/[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.2 - (hide annotations) (download)
Tue Aug 12 17:02:43 2003 UTC (10 years, 8 months ago) by g2boojum
Branch: MAIN
Changes since 1.1: +110 -87 lines
File MIME type: text/plain
Update.

1 g2boojum 1.1 GLEP: 11
2     Title: Web Application Installation
3 g2boojum 1.2 Version: $Revision: 1.2 $
4     Last-Modified: $Date: 2003/08/12 23:14:00 $
5 g2boojum 1.1 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 g2boojum 1.2 Post-History: 07 Aug 2003, 12 Aug 2003
12 g2boojum 1.1
13     Credits
14     =======
15    
16     Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
17     [#WebAppPost2]_ [#WebAppPost3]_ by:
18    
19 g2boojum 1.2 Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>,
20     Robin H.Johnson <robbat2 at gentoo.org> and others
21 g2boojum 1.1
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 g2boojum 1.2 i. Web Application must be slotted by their full version numbers to
91 g2boojum 1.1 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 g2boojum 1.2 Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that
103 g2boojum 1.1 implements a good deal of this GLEP.
104    
105 g2boojum 1.2 Stuart Herbert <stuart at gentoo.org> has committed::
106 g2boojum 1.1
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 g2boojum 1.2 -------------
114 g2boojum 1.1
115 g2boojum 1.2 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 g2boojum 1.1
125     1.1 Default Document Root
126     '''''''''''''''''''''''''
127    
128 g2boojum 1.2 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 g2boojum 1.1 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 g2boojum 1.2 /var/www/localhost/
142    
143     * For multiple virtual host installations::
144 g2boojum 1.1
145 g2boojum 1.2 /var/www/<fully qualified domain name>/
146 g2boojum 1.1
147     eg:
148 g2boojum 1.2 /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 g2boojum 1.1
153     1.2 Apache 2
154 g2boojum 1.2 ''''''''''''
155 g2boojum 1.1
156 g2boojum 1.2 All web application .ebuilds will honour any USE flags that are intended to
157 g2boojum 1.1 add support for Apache 2 as well as supporting Apache 1 installations.
158    
159 g2boojum 1.2 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 g2boojum 1.1
169 g2boojum 1.2 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 g2boojum 1.1
199 g2boojum 1.2 The ability to easily configure and administer multiple virtual hosts is a
200     must.
201 g2boojum 1.1
202 g2boojum 1.2 3.1 New "vhost" USE Flag
203 g2boojum 1.1 ''''''''''''''''''''''''
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 g2boojum 1.2 3.2 VHost Configuration Tool
214 g2boojum 1.1 ''''''''''''''''''''''''''''
215    
216     To assist administration of multiple virtual hosts a "VHost Configuration Tool"
217 g2boojum 1.2 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 g2boojum 1.1
223     The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
224     Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).
225    
226 g2boojum 1.2 `Bug #26293`_ will be used to track the initial progress of the VHost
227     Configuration Tool.
228 g2boojum 1.1
229 g2boojum 1.2 .. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
230 g2boojum 1.1
231    
232 g2boojum 1.2 The vhost-config must do three main things:
233 g2boojum 1.1
234 g2boojum 1.2 - creates directories (copies a skeleton directory for the most part).
235     - create web server vhost config files.
236     - HUP web server so it reads in the new config without stopping.
237 g2boojum 1.1
238 g2boojum 1.2 Initially the VHost Config tool should provide support for the Apache web
239     server. As the tool matures support for other web servers can be added.
240 g2boojum 1.1
241 g2boojum 1.2 4.1 Single Host Installation
242 g2boojum 1.1 ''''''''''''''''''''''''''''
243    
244     For single host installations the .ebuild will make the required
245     configurations changes and symlinks using the VHost Config tool to ensure
246     that the web application is available to be served from::
247    
248 g2boojum 1.2 /var/www/localhost/htdocs/${PF}/
249    
250     In this case it may be feasible for the VHost Config tool to simply symlink the
251     directories from /usr/share/webapps/${PF}/ as is appropriate.
252 g2boojum 1.1
253 g2boojum 1.2 4.2 Virtual Host Installation
254 g2boojum 1.1 '''''''''''''''''''''''''''''
255    
256     For installations that support multiple virtual hosts the .ebuild will
257     install the web application into the default location and then leave configuration
258     to the user through the VHost Config tool.
259    
260 g2boojum 1.2 In this case the web application files will be copied from
261     /usr/share/webapps/${PF}/ to /var/www/<FQDN>/ by the VHost Config tool.
262 g2boojum 1.1
263 g2boojum 1.2 4.3 Configuration Files
264     '''''''''''''''''''''''
265 g2boojum 1.1
266 g2boojum 1.2 As stated above web application *site default* configuration files are to be
267     installed into::
268 g2boojum 1.1
269     /etc/webapps/${PF}/
270    
271 g2boojum 1.2 The files in this directory are then copied (not symlinked!) by the VHost
272     Config tool to the Document Root for each instance of the app that is installed.
273 g2boojum 1.1
274 g2boojum 1.2 This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
275     behaviour for the web applications.
276 g2boojum 1.1
277     5. Application Permissions
278     --------------------------
279    
280     Installing web applications and giving the web server ownership of the files
281     is a security risk. This can possibly lead to application configuration
282     files being accessed by unwanted third parties.
283    
284     All web applications should be owned by *root* unless the application
285     absolutely requires write access to its installation directories at execution
286     time.
287    
288     Backwards Compatibility
289     =======================
290    
291     There may be some issues regarding compatibility with existing installs of
292     web applications. This is particularly true if the default Document Root is
293     moved from what is accepted as the current standard (/home/httpd).
294    
295     The main issues are:
296     * transition of existing configuration files to the
297     /etc/webapps/${PF}/ directory.
298     * modification/reconfiguration of applications so that they
299     are aware of the location of configuration files.
300 g2boojum 1.2 * creating the VHost Config toolset to enable installation and
301     configuration of web applications irrespective of web server.
302 g2boojum 1.1
303    
304     References
305     ==========
306    
307     .. [#WebAppPost1] http://article.gmane.org/gmane.linux.gentoo.devel/10411
308     .. [#WebAppPost2] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C1059843010.5023.80.camel%40carbon.internal.lan%3E
309     .. [#WebAppPost3] http://news.gmane.org/onethread.php?group=gmane.linux.gentoo.devel&root=%3C86960000.1060038977%40valkyrie.lsit.ucsb.edu%3E
310    
311     Copyright
312     =========
313    
314     This document has been placed in the public domain.

  ViewVC Help
Powered by ViewVC 1.1.20