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

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

  ViewVC Help
Powered by ViewVC 1.1.20