webapp.eclass Documentation

1.  Introduction

Background

webapp.eclass and webapp-config provide a standardized way to maintain web applications in 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 prepare the application for installation into multiple virtual hosts. In Gentoo, this is done by an ebuild that uses webapp.eclass.

The goal of this guide is to show the reader how to create and maintain ebuilds for web applications. It presents an overview of webapp.eclass and then discusses three ebuilds of increasing complexity 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 format. Both are well-documented; the reader is encouraged to consult the official ebuild HOWTO and the 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.14. You can follow the 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 to 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.

By default, webapp.eclass will be found under /usr/portage/eclass/. The source code is the ultimate documentation and should be consulted whenever something does not perform as expected or further clarification is required.

2.  Writing Ebuilds

Beginner: www-apps/gallery-2.0.2

Many web applications require no compilation and are installed by copying their files to a directory to be served by a httpd server such as Apache. 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

The ebuild then sets several standard variables, such as DESCRIPTION, IUSE, RDEPEND, and S. The first important note is that ebuilds that use webapp.eclass do not typically set the SLOT 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 it.

www-apps/gallery-2.0.2 does not require patching or compiling, so the ebuild does not call src_unpack or src_compile; installation is handled in src_install. The first thing src_install does is call a special helper function that sets up the required directory structure:

src_install() {
  webapp_src_preinst

This function is required of all ebuilds that use 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 right directory under the webserver's document root by webapp-config. For 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 application has been installed:

webapp_postinst_txt en ${FILESDIR}/postinstall-en2.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 settings.

  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 display time. The webapp-config utility responsible for displaying the file exports a number of variables that allow for the customization of instructions. 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 permissions on installed files.

There are several best practices for writing simple ebuilds:

• Don't copy unneeded files. Some packages include .svn or CVS directories or Makefiles; those should be removed prior to installation. Note that the LICENSE file 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 must, remove files from ${D} rather than ${S}.
• For portability purposes, don't use GNU-only extensions such as cp -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. Let's look at how www-apps/tikiwiki-1.9.2 handles one such package. After inheriting the eclass, the ebuild specifies a number of required and optional dependencies.

RDEPEND="virtual/php
  graphviz? ( media-gfx/graphviz )
"

Many web-applications written in PHP require that the PHP binary have certain capabilities built-in; common requirements include support for sessions and a specific database engine. This is typically accomplished by using the depend.php eclass. Please consult that eclass for further information.

www-apps/tikiwiki uses depend.php to check for a properly configured PHP:

pkg_setup () {
  webapp_pkg_setup
  use mysql && require_php_with_use mysql
  use postgres && require_php_with_use postgres
}

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 permissions:

webapp_serverowned ${MY_HTDOCSDIR}/tiki-install.php

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

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

webapp_configfile ${MY_HTDOCSDIR}/config.php

To ease upgrades of web applications, the eclass provides a helper function that displays instructions when an existing installation is being upgraded:

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

Even though few ebuilds in Portage currently take advantage of this functionality, the reader is encouraged to use it in his ebuilds.

The ebuild calls the familiar helper function to complete the installation. 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() {
  elog "To setup a MySQL database, run:"
  elog "\"emerge --config =${PF}\""
  elog "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 to 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 provided by webapp.eclass. An example of this functionality is www-apps/moinmoin-1.5.0.

moinmoin is a wiki engine written in Python that uses distutils to install itself. Thus, it requires SLOT="0" to avoid collisions. Ebuilds that inherit webapp.eclass must set WEBAPP_MANUAL_SLOT="yes" to override the default SLOTting behavior:

SLOT="0"
WEBAPP_MANUAL_SLOT="yes"

moinmoin installs files that should not be served by the webserver. 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 after 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 invoked by webapp-config after installation and before removal.

#!/bin/bash

die() {
  echo "#####"
  echo $1
  echo "#####"
  exit 1
}

if [ $1 = "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 = "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 may differ from the default values. As of webapp-config-1.50, reconfig hooks are run in a sandbox to minimize risk; please consult the manpage for more 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.

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

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

3.  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 restart. Is is better to either install the file elsewhere and let the administrator customize it, or comment out the contents to avoid failure.

4.  Next Steps

Obtaining More Information

Additional examples can be found in the www-apps category of 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 feel free to contact the web-apps team or ask in #gentoo-web on Freenode.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.