webapp.eclass Documentation

- -1.0 -2006-01-17 - - -Introduction -

-Background - - -

-webapp.eclass and webapp-config provide a standardized way= to -maintain web applications on Gentoo. Server administrators can use the -webapp-config utility to install, upgrade, and remove software. -webapp-config relies on a package manager such as Portage to prep= are -the application for installation into multiple virtual hosts. On Gentoo,= this -is done by an ebuild that uses webapp.eclass. -

- -

-The goal of this guide is to teach the reader how to create and maintain -ebuilds for web applications. It presents an overview of the -webapp.eclass and then discusses three ebuilds of increasing comp= lexity -and functionality. Using the webapp-config utility is beyond the = scope -of this guide and is documented in man 8 webapp-config. -

- - -

-Prerequisites - - -

-This guide assumes a basic familiarity with Portage and the ebuild forma= t. Both -are well-documented; the reader is encouraged to consult the official ebuild HOWTO and -the unofficial devmanual. -

- -

-webapp-config is under active development. Be sure to install the= latest -version; as of the time of this writing, it is 1.50.7. You can follow th= e -development process on our website. -

- - -

-A standardized approach to installing web applications - - -

-Gentoo has developed a standardized way of handling web applications. It= is -outlined in GLEP 11 and -discussed in detail in man 5 webapp.eclass. The reader is urged t= o -familiarize himself with these documents before proceeding. The manpage = also -outlines the filesystem locations into which the eclass and -webapp-config install files; advanced users and developers should= take -note. -

- -

-The webapp.eclass is located in the usual place in the Portage tr= ee. By -default, it will be found in /usr/portage/eclass/webapp.eclass. By -definition, the source code is the ultimate documentation and should be -consulted whenever something does not perform as expected or further -clarification is required. -

- -

- - - -Writing Ebuilds -

-Beginner: www-apps/gallery-2.0.2 - - -

-Many web applications require no compilation and are installed by copyin= g their -files to a directory to be served by a httpd server such as Apache. The -webapp.eclass simplifies this task by preparing the necessary set= of -directories. -

- -

-Let's take a look at a simple ebuild for www-apps/gallery-2.0.2. -To use any of the functions in the eclass, the ebuild must first inherit= it: -

- -

-inherit webapp.eclass
-

- -

-The ebuild then sets several standard variables, such as DESCRIPTION<= /c>, -IUSE, RDEPEND, and S. The first important note is t= hat -ebuilds that use the webapp.eclass do not typically set the SL= OT -variable (the rationale for this is described in the manpage). Section 2.3 will explain how SLOT= can be -set when it is truly needed, but for now we will let the eclass handle i= t. -

- - -Unless explicitly overridden, the eclass sets SLOT=3D"${PVR}". On= e -important downside of this behavior is that security revision bumps are = no -longer possible. This is unfortunate and will be changed soon. - - -

-www-apps/gallery-2.0.2 does not require patching or compili= ng, so -the ebuild does not call src_unpack or src_compile; instal= lation -is handled in src_install. The first thing src_install doe= s is -call a special helper function that sets up the required directory struc= ture: -

- -

-src_install() {
-  webapp_src_preinst
-

- -

-This function is required of all ebuilds that use the webapp.eclass and -override the default src_install. -

- -

-Having set up the environment, the ebuild installs the web application: -

- -

-cp -R * ${D}/${MY_HTDOCSDIR}
-

- -

-${MY_HTDOCSDIR} is one of the variables exported by -webapp_src_preinst. Files placed there will be copied into the ri= ght -directory under the webserver's document root by webapp-config. F= or a -full list of variables exported by the eclass, please see the manpage. -

- -

-Next, the ebuild marks a file in ${FILESDIR} as a file containing -instructions to be displayed by webapp-config after the applicati= on has -been installed: -

- -

-webapp_postinst_txt en ${FILESDIR}/postinstall-en2.txt
-

- - -A careful reader will observe that it is customary for other ebuilds to = display -instructions to the user in pkg_postinst. Ebuilds that inherit -webapp.eclass may still do so, but the ebuild author should under= stand -the important difference in usage. More often than not, post-install -instructions include information specific to a virtual host, such as loc= ations -of a particular configuration file or a URL to access the web applicatio= n -remotely. This information is not available to Portage and cannot be inc= luded -in pkg_postinst. Instead, it should be included in a post-install= file -and installed using webapp_postinstall_txt. - - -

-Let's examine a typical post-install file: -

- -

-  0. Create a new MySQL database:
-  mysqladmin create geeklog
-
-  1. Edit ${VHOST_ROOT}/${PN}-${PVR}/config.php and set database setting=
s.
-
-  2. Login on
-  http://${VHOST_HOSTNAME}/${VHOST_APPDIR}/admin/install/install.php
-  and follow the directions.
-
-  3. Don't forget to delete the admin/install directory when you're done=
!
-

- -

-Post-install instruction files are plain text files. They can contain -bash-style variables (e.g., ${PN}) that will be expanded at displ= ay -time. The webapp-config utility responsible for displaying the fi= le -exports a number of variables that allow for the customization of instru= ctions. -Consult the manpage for a list of available variables. -

- -

-Finally, the ebuild calls another mandatory helper function: -

- -

-webapp_src_install
-

- -

-webapp_src_install is responsible for setting the right permissio= ns on -installed files. -

- -

-There are several best practices for writing simple ebuilds: -

- -

- Don't copy unneeded files. Some packages include .svn o= r - CVS directories or Makefiles; those should= be - removed prior to installation. Note that the LICENSE fi= le is - sometimes needed by the application and should not be removed. -
- Ensure that consecutive calls to all ebuild functions succeed. For - instance, don't remove files outside of src_unpack. If you mu= st, - remove files from ${D} rather than ${S}. -
- For portability purposes, don't use GNU-only extensions such as c= p - -a. They will break on non-GNU userlands such as Gentoo/FreeBSD. -

- - -

-Intermediate: www-apps/tikiwiki-1.9.2 - - -

-Many web applications have a more complicated installation procedure. Le= t's -look at how www-apps/tikiwiki-1.9.2 -handles one such package. After inheriting the eclass, the ebuild specif= ies a -number of required and optional dependencies. -

- -

-RDEPEND=3D"virtual/php
-  mysql? ( >=3Ddev-db/mysql-4 )
-  postgres? ( dev-db/postgresql )
-  graphviz? ( media-gfx/graphviz )
-"
-

- -

-Many web-applications written in PHP require that the PHP binary have ce= rtain -capabilities built-in; common requirements include support for sessions = and a -specific database engine. This is typically accomplished by using the -depend.php eclass; unfortunately, the author is not aware of any = existing -documentation for that eclass. The reader is referred to the eclass itse= lf for -further information and encouraged to consult relevant ebuilds in Portag= e. -

- - -If the package requires specific Perl modules, all dependencies must hav= e -ebuilds available. Relying on CPAN is not acceptable. - - -

-A common mistake with specifying dependencies for web applications is to -unconditionally RDEPEND on a database engine such as MySQL or -PostgreSQL. Many, if not all, web applications are able to connect to a= remote -database server. Thus, a local database should not be a requirement; the= right -syntax for dealing with this is: -

- -

-mysql? ( >=3Ddev-db/mysql-4 )
-

- - -It is currently not possible to depend on a generic webserver. Instead, = you -must explicitly specify the webserver (e.g., net-www/apache= ). This -is inconvenient and has been reported in bug #11007= ; we hope -that this issue will be resolved soon. - - -

-www-apps/tikiwiki does not use depend.php and instea= d uses -pkg_setup to print a warning: -

- -

-pkg_setup () {
-  webapp_pkg_setup
-  einfo "Make sure your PHP is compiled with mysql or postgres support"
-  einfo "If you need PDF generation, make sure your PHP is emerged with =
xml2"
-}
-

- -

-Note the use of a mandatory helper function webapp_pkg_setup. -

- -

-Many web applications require write access to certain files. The eclass -provides a helper function that marks a file as server-owned; at install= time, -webapp-config will ensure that it has the right owner and permiss= ions: -

- -

-webapp_serverowned ${MY_HTDOCSDIR}/tiki-install.php
-

- -

-webapp_serverowned takes an optional -R flag to recurse in= to -subdirectories. This flag has been added recently and not many ebuilds t= ake -advantage of it. Please consult the manpage for more information. -

- -

-Practically all web applications use configuration files to store settin= gs. -Such files should not be placed into /etc (figuring out the -rationale is left as an exercise for the reader). To avoid losing import= ant -configuration information, the eclass provides another helper function t= hat -will instruct webapp-config not to overwrite an existing file. Th= e -administrator can use familiar tools such as etc-update or -dispatch-conf to manage such files. -

- -

-webapp_configfile ${MY_HTDOCSDIR}/config.php
-

- -

-Note that it is currently not possible to mark a file as both server-own= ed and -config-protected. This has been fixed in an upcoming version of -webapp-config. For now, there is a workaround described in Section 2.3. -

- -

-To ease upgrades of web applications, the eclass provides a helper funct= ion -that displays instructions when an existing installation is being upgrad= ed: -

- -

-webapp_postupgrade_txt en ${FILESDIR}/postupgrade-en.txt
-

- -

-Even though no ebuilds in Portage currently take advantage this function= ality, -the reader is encouraged to use it in his ebuilds. -

- -

-The ebuild calls the familiar helper function to complete the installati= on. -Note an important consequence of using webapp_src_install to set = the -correct file permissions: any manual adjustments to file permissions and -ownership via fowners and fperms must occur after -webapp_src_install is called. -

- -

-webapp_src_install
-fperms 0644 /etc/zm.conf
-

- -

-The tikiwiki ebuild displays some brief notes using pkg_postinst.= Note -the use of another helper function: -

- -

-pkg_postinst() {
-  einfo "To setup a MySQL database, run:"
-  einfo "\"emerge --config =3D${PF}\""
-  einfo "If you are using PostgreSQL, consult your documentation"
-  webapp_pkg_postinst
-}
-

- -

-Strictly speaking, webapp_pkg_postinst is not mandatory. It is -responsible for automatically calling webapp-config when the -vhosts USE flag is unset. In rare instances it may be desirable t= o -override this behavior; please consult www-apps/otrs for an -example. -

- - -

-Advanced: www-apps/moinmoin-1.5.0 - - -

-This section presents an overview of more advanced installation tasks pr= ovided -by the webapp.eclass. An example of this functionality is www-apps/moinmoin-1.5.0. -

- -

-moinmoin is a wiki engine written in Python that uses distutil= s -to install itself. Thus, it requires SLOT=3D"0" to avoid collisio= ns. -Ebuilds that inherit webapp.eclass must set -WEBAPP_MANUAL_SLOT=3D"yes" to override the default SLOTtin= g -behavior: -

- -

-SLOT=3D"0"
-WEBAPP_MANUAL_SLOT=3D"yes"
-

- - -The yes in WEBAPP_MANUAL_SLOT=3D"yes" is case-sensitive. - - -

-moinmoin installs files that should not be served by the webserve= r. The -ebuild places such files in ${MY_HOSTROOTDIR}/${PF}. -

- -

-dodir ${MY_HOSTROOTDIR}/${PF}
-cp -r data underlay config/wikiconfig.py ${D}/${MY_HOSTROOTDIR}/${PF}
-

- -

-A best practice for installing any application via Portage is to ensure = it -operates out of the proverbial box with sensible defaults. The eclass -implements a helper function to aid with configuring the application aft= er it -has been installed by webapp-config. -

- -

-webapp_hook_script ${FILESDIR}/reconfig-2
-

- -

-The reconfig hook is a script, typically written in bash, that is invoke= d by -webapp-config after installation and before removal. -

- -

-#!/bin/bash
-
-die() {
-  echo "#####"
-  echo $1
-  echo "#####"
-  exit 1
-}
-
-if [ $1 =3D "install" ]; then
-  sed -e "s|/path/to/wikiconfig|${VHOST_ROOT}/${PN}-${PVR}|g" \
-    -i ${MY_INSTALLDIR}/moin.cgi || die "sed failed"
-  sed -e "s|\./data/|${VHOST_ROOT}/${PN}-${PVR}/data|
-    s|\./underlay/|${VHOST_ROOT}/${PN}-${PVR}/underlay|" \
-    -i ${VHOST_ROOT}/${PN}-${PVR}/wikiconfig.py || die "sed failed"
-
-elif [ $1 =3D "clean" ]; then
-  echo $1
-fi
-

- -

-The reconfig hook can use the same variables as the postinstall file. It= is -typically used to edit configuration files to set file locations that ma= y -differ from the default values. As of webapp-config-1.50, reconfi= g hooks -are run in a sandbox to minimize risk; please consult the manpage for mo= re -details. -

- -

-There are several best practices for using reconfig hooks: -

- -

Die with an error message if the script failed
- Be careful about removing files when called with clean. Don't= remove - configuration files or any other files that may have been locally - modified. -
- To mark a file as both config-protected and server-owned, use - webapp_configfile from the ebuild and use the reconfig hook t= o mark - it as server-owned: -

- -

-chown ${VHOST_SERVER_UID}:${VHOST_SERVER_GID} ${MY_INSTALLDIR}/Settings.=
php
-

- -

-The eclass provides several other functions that are rarely used. The mo= st -notable is webapp_sqlscript, which marks a file as an SQL create = script. -In its current state, this function is only moderately useful. -

- - -

- - - -Additional Best Practices -

-Apache - - -

- Be careful when installing apache configuration files. If you place = a - misconfigured Apache configuration file into - /etc/apache{2}/vhosts.d, the server will fail on next r= estart. - Is is better to either install the file elsewhere and let the admini= strator - customize it, or comment out the contents to avoid failure. -

- - -

- - - -Next Steps -

-Obtaining More Information - - -

-Additional examples can be found in the www-apps category o= f the -Portage tree. Developers and users should also consult the web-apps -overlay for even more examples and software packages. -

- -

-If you have a question that is not answered in this document, please fee= l free -to contact the web-apps -herd or ask on IRC. -

- - -

- -