/[gentoo]/xml/htdocs/proj/en/glep/glep-0011.txt
Gentoo

Diff of /xml/htdocs/proj/en/glep/glep-0011.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.6
1GLEP: 11 1GLEP: 11
2Title: Web Application Installation 2Title: Web Application Installation
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.6 $
4Last-Modified: $Date: 2003/08/07 19:02:40 $ 4Last-Modified: $Date: 2006/09/04 03:12:43 $
5Author: Troy Dack <tad@gentoo.org> 5Author: Troy Dack <tad@gentoo.org>
6Author: Stuart Herbert <stuart@gentoo.org>
6Discussions-To: gentoo-dev@gentoo.org 7Discussions-To: gentoo-dev@gentoo.org
7Status: Draft 8Status: Final
8Type: Standards Track 9Type: Standards Track
9Content-Type: text/x-rst 10Content-Type: text/x-rst
10Created: 02 August 2003 11Created: 02-August-2003
11Post-History: 07 Aug 2003 12Post-History: 07-Aug-2003, 12-Aug-2003, 13-Aug-2003, 3-Sep-2006
13
14Status
15======
16
17As of 2006-09-03 the webapp eclass has existed for some time.
12 18
13Credits 19Credits
14======= 20=======
15 21
16Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_ 22Based on comments posted to gentoo-dev mailing list [#WebAppPost1]_
17[#WebAppPost2]_ [#WebAppPost3]_ by: 23[#WebAppPost2]_ [#WebAppPost3]_ by:
18 24
19 Stuart Herbert <stuart@gentoo.org>, Max Kalika <max@gentoo.org>, 25 Stuart Herbert <stuart at gentoo.org>, Max Kalika <max at gentoo.org>,
20 Robin H.Johnson <robbat2@gentoo.org> and others 26 Robin H.Johnson <robbat2 at gentoo.org> and others
21 27
22Definitions 28Definitions
23=========== 29===========
24 30
25 *Web Application* 31 *Web Application*
85 1. Gentoo installed web applications (eg: horde, phpbb, cacti, 91 1. Gentoo installed web applications (eg: horde, phpbb, cacti,
86 phpmysql) should not be installed in the Document Root of a web server. 92 phpmysql) should not be installed in the Document Root of a web server.
87 2. Web applications should not have their configuration files installed 93 2. Web applications should not have their configuration files installed
88 under the Document Root of a web server. 94 under the Document Root of a web server.
89 95
90 i. Web Application must be slotted by their major version numbers to 96 i. Web Application must be slotted by their full version numbers to
91 further avoid downtime when true configuration changes are required. 97 further avoid downtime when true configuration changes are required.
92 98
93 3. Web applications should not be owned by the same user as the web server. 99 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 100 4. It should be easily possible to have multiple instances of a web
95 application without any duplication of source files. 101 application without any duplication of source files.
97 application. 103 application.
98 104
99Implementation 105Implementation
100============== 106==============
101 107
102Max Kalika <max@gentoo.org> stated that he has a preliminary eclass that 108Max Kalika <max at gentoo.org> stated that he has a preliminary eclass that
103implements a good deal of this GLEP. 109implements a good deal of this GLEP.
104 110
105Stuart Herbert <stuart@gentoo.org> has committed:: 111Stuart Herbert <stuart at gentoo.org> has committed::
106 112
107 webapp-apache.eclass 113 webapp-apache.eclass
108 114
109to CVS, this is a stop-gap measure whilst this GLEP is being finalised. 115to CVS, this is a stop-gap measure whilst this GLEP is being finalised.
110 116
111 117
1121. Web Server 1181. Web Server
113--------------------- 119-------------
114 120
115A common default web server will have to be selected and ebuild authors should 121A common default web server should be selected. Selection of a default web
116ensure that their applications contain configuration directives suitable for 122server will help to reduce the number of bugs that are reported.
123
117that server. Given the popularity of the Apache web server it is suggested 124Given the popularity of the Apache web server it is suggested that Apache be
118that Apache be selected as the Gentoo default web server. 125selected as the Gentoo default web server.
119 126
120Whilst it is acknowledged that other web servers do exist and are used, there 127The Virtual Host Configuration tool (see below) will transparently support
121has to be an assumption made somewhere that people who choose to use something 128different web servers, thus enabling web applications to be installed on a
122other than the default have enough knowledge to adapt configurations 129Gentoo system irrespective of the installed web server.
123accordingly.
124 130
1251.1 Default Document Root 1311.1 Default Document Root
126''''''''''''''''''''''''' 132'''''''''''''''''''''''''
127 133
134The current default Document Root for Gentoo is /home/httpd/, this is
135unsuitable 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
128To ensure the greatest flexibility when installing applications the following 142To ensure the greatest flexibility when installing applications the following
129*Document Root* locations are to be used: 143*Document Root* locations are to be used:
130 144
131 * For single host installations:: 145 * For single host installations::
132 146
133 /var/www/localhost/htdocs/ 147 /var/www/localhost/
134 148
135 * For multiple virtual host installastions:: 149 * For multiple virtual host installations::
136 150
137 /var/www/<fully qualified domain name>/htdocs/ 151 /var/www/<fully qualified domain name>/
152
138 eg: 153 eg:
139 /var/www/www.gentoo.org/htdocs/ 154 /var/www/www.gentoo.org/
155
156Additionally the chosen location ( /var/www/ ) appears to be becoming a defacto
157standard for Linux distributions.
140 158
1411.2 Apache 2 1591.2 Apache 2
142'''''''''''''''''''''''' 160''''''''''''
143 161
144All web application .ebuild will honour any USE flags that are intended to 162All web application .ebuilds will honour any USE flags that are intended to
145add support for Apache 2 as well as supporting Apache 1 installations. 163add support for Apache 2 as well as supporting Apache 1 installations.
146 164
147 1652. Application Installation
1482. Virtual Host Flexibility
149--------------------------- 166---------------------------
150
151In a similar vein to Gentoo's Zope scripts, namely zope-config, we
152should be able to have multiple instances of a single web application
153without duplicating all of the files.
154
155This also allows system administrators to control where web applications
156will appear on their system, as well as to customize a file in a single
157instance of a web application without effecting the original material.
158
159This is easily acheived thru use of Apache configuration directivies and
160symlinks. For PHP instances, see http://tavi.sourceforge.net/VirtualHosts
161for some details.
162
163The primary idea here is that to the web-application, it appears that
164all of it's configuration and files are in the instance directory, but
165the files are physicalled located elsewhere.
166
1672.1 New "vhost" USE Flag
168''''''''''''''''''''''''
169
170To enable support for multiple virtual host installations a new USE flag is
171to be added to Portage. The use flag will be::
172
173 vhost
174
175When *vhost* is _set_ the installation location and configuration for the web
176application will be effected, see below for more details.
177
1782.2 VHost Configuration Tool
179''''''''''''''''''''''''''''
180
181To assist administration of multiple virtual hosts a "VHost Configuration Tool"
182needs to be developed and implemented. Initial discussion and regarding the VHost
183Config tool can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
184
185The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
186Apache .ebuilds will require the VHost Config tool as a dependency (DEPEND).
187
188<< TO BE EXPANDED UPON >>
189
1903. Application Installation Location
191------------------------------------
192 167
193The current accepted standard Document Root in Gentoo is /home/httpd. The 168The current accepted standard Document Root in Gentoo is /home/httpd. The
194discussion suggest that this is not the best location to install web based 169discussion suggest that this is not the best location to install web based
195applications. 170applications.
196 171
1722.1 Application SLOTs
173'''''''''''''''''''''
174
175All ebuilds are to set the SLOT variable as follows::
176
177 SLOT="${PV}"
178
179Setting the SLOT variable as shown will enable different versions of the same
180web application to be served concurrently by one server.
181
1822.2 Installation Paths
183''''''''''''''''''''''
184
197Web applications should be installed outside of the Document Root using the following 185Web applications should be installed outside of the Document Root using the following
198defaults: 186defaults:
199 187
200 * for files to be served to clients:: 188 * for files to be served to clients::
201 189
202 /usr/share/webapps/${PF}/ 190 /usr/share/webapps/${PF}/htdocs/
203 191
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 192 /usr/share/webapps/${PF}/cgi-bin/
207 193
208 * install configuration files in:: 194 * install *site default* configuration files in::
209 195
210 /etc/webapps/${PF}/ 196 /etc/webapps/${PF}/
211 197
212 * for documentation files (not served to clients):: 198 * for documentation files (not served to clients)::
213 199
214 /usr/share/doc/${PF}/ 200 /usr/share/doc/${PF}/
215 201
2023. Virtual Host Support
203-----------------------
204
205The ability to easily configure and administer multiple virtual hosts is a
206must.
207
2083.1 New "vhost" USE Flag
209''''''''''''''''''''''''
210
211To enable support for multiple virtual host installations a new USE flag is
212to be added to Portage. The use flag will be::
213
214 vhost
215
216When *vhost* is _set_ the installation location and configuration for the web
217application will be effected, see below for more details.
218
2193.2 VHost Configuration Tool
220''''''''''''''''''''''''''''
221
222To assist administration of multiple virtual hosts a "VHost Configuration Tool"
223needs to be developed and implemented. Initial discussion regarding the VHost
224Config tool and proposed usage can be found at http://article.gmane.org/gmane.linux.gentoo.devel/10874.
225
226It's the job of the VHost Config toolset to make a local instance of the web
227application run under a specific web server.
228
229The VHost Configuration Utility will need to be a seperate package, maintained by Gentoo.
230
231Web 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
234Configuration Tool.
235
236.. _Bug #26293: http://bugs.gentoo.org/show_bug.cgi?id=26293
237
238
239The 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
245Initially the VHost Config tool should provide support for the Apache web
246server. As the tool matures support for other web servers can be added.
247
2163.1 Single Host Installation 2483.3 Single Host Installation
217'''''''''''''''''''''''''''' 249''''''''''''''''''''''''''''
218 250
219For single host installations the .ebuild will make the required 251For single host installations the .ebuild will make the required
220configurations changes and symlinks using the VHost Config tool to ensure 252configurations changes and symlinks using the VHost Config tool to ensure
221that the web application is available to be served from:: 253that the web application is available to be served from::
222 254
223 /var/www/localhost/htdocs/${PN} 255 /var/www/localhost/htdocs/${PF}/
224 256
257In this case it may be feasible for the VHost Config tool to simply symlink the
258directories from /usr/share/webapps/${PF}/ as is appropriate.
259
2253.2 Virtual Host Installation 2603.4 Virtual Host Installation
226''''''''''''''''''''''''''''' 261'''''''''''''''''''''''''''''
227 262
228For installations that support multiple virtual hosts the .ebuild will 263For installations that support multiple virtual hosts the .ebuild will
229install the web application into the default location and then leave configuration 264install the web application into the default location and then leave configuration
230to the user through the VHost Config tool. 265to the user through the VHost Config tool.
231 266
232<< TO BE EXPANDED UPON >> 267In this case the web application files will be copied from
268/usr/share/webapps/${PF}/ to /var/www/<FQDN>/ by the VHost Config tool.
233 269
2344. Application Configuration 2703.5 Configuration Files
235---------------------------- 271'''''''''''''''''''''''
236 272
237Having application configuration files in the Document Root of a web
238server is a potential security risk. Additionally given the way that many
239ebuilds currently install web applications it can also lead to the
240overwriting of important configuration files.
241
242As stated above web application configuration files are to be installed into:: 273As stated above web application *site default* configuration files are to be
274installed into::
243 275
244 /etc/webapps/${PF}/ 276 /etc/webapps/${PF}/
245 277
246By installing application configuration files in /etc Portage CONFIG_PROTECT 278The files in this directory are then copied (not symlinked!) by the VHost
247features can be used to ensure that configuration files are not overwritten. 279Config tool to the Document Root for each instance of the app that is installed.
248 280
2494.1 Virtual Host Support 281This will require the VHost Config toolset to emulate Portage's CONFIG_PROTECT
250'''''''''''''''''''''''' 282behaviour for the web applications.
251 283
252<< TO BE EXPANDED UPON >>
253
2545. Application Permissions 2844. Application Permissions
255-------------------------- 285--------------------------
256 286
257Installing web applications and giving the web server ownership of the files 287Installing web applications and giving the web server ownership of the files
258is a security risk. This can possibly lead to application configuration 288is a security risk. This can possibly lead to application configuration
259files being accessed by unwanted third parties. 289files being accessed by unwanted third parties.
272The main issues are: 302The main issues are:
273 * transition of existing configuration files to the 303 * transition of existing configuration files to the
274 /etc/webapps/${PF}/ directory. 304 /etc/webapps/${PF}/ directory.
275 * modification/reconfiguration of applications so that they 305 * modification/reconfiguration of applications so that they
276 are aware of the location of configuration files. 306 are aware of the location of configuration files.
277 * creating approriate Apache configuration snippets for inclusion 307 * creating the VHost Config toolset to enable installation and
278 in the Apache configuration files. 308 configuration of web applications irrespective of web server.
279 309
280 310
281References 311References
282========== 312==========
283 313
287 317
288Copyright 318Copyright
289========= 319=========
290 320
291This document has been placed in the public domain. 321This document has been placed in the public domain.
292

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.6

  ViewVC Help
Powered by ViewVC 1.1.20