Project:Webapps/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 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.

Background
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.

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 ourwebsite.

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 man page also outlines the filesystem locations into which the eclass and webapp-config install files; advanced users and developers should take note.

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

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. simplifies this task by preparing the necessary set of directories.

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:

The ebuild then sets several standard variables, such as,  ,  , and. The first important note is that ebuilds that use do not typically set the   variable (the rationale for this is described in the man page). will explain how  can be set when it is truly needed, but for now we will let the eclass handle it.

does not require patching or compiling, so the ebuild does not call  or  ; installation is handled in. The first thing  does is call a special helper function that sets up the required directory structure:

{{CodeBox|title=Setting up src_install|lang=bash|1= src_install { webapp_src_preinst }}

This function is required of all ebuilds that use and override the default.

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

is one of the variables exported by. Files placed there will be copied into the right directory under the web server's document root by webapp-config</tt>. For a full list of variables exported by the eclass, please see the man page.

Next, the ebuild marks a file in  as a file containing instructions to be displayed by webapp-config</tt> after the application has been installed:

Examine a typical post-install file:

Post-install instruction files are plain text files. They can contain bash-style variables (e.g., ) that will be expanded at display time. The webapp-config</tt> utility responsible for displaying the file exports a number of variables that allow for the customization of instructions. Consult the man page for a list of available variables.

Finally, the ebuild calls another mandatory helper function:

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 or  directories or ; those should be removed prior to installation. Note that the  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 . If you must, remove files from   rather than.
 * For portability purposes, don't use GNU-only extensions such as cp -a</tt>. 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.

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 eclass. Please consult that eclass for further information.

uses to check for a properly configured PHP:

Note the use of a mandatory helper function.

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</tt> will ensure that it has the right owner and permissions:

takes an optional  flag to recurse into sub-directories. This flag has been added recently and not many ebuilds take advantage of it. Please consult the man page for more information.

Practically all web applications use configuration files to store settings. Such files should not be placed into (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</tt> not to overwrite an existing file. The administrator can use familiar tools such as etc-update</tt> or dispatch-conf</tt> to manage such files.

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

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  to set the correct file permissions: any manual adjustments to file permissions and ownership via   and   must occur after   is called.

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

Strictly speaking,  is not mandatory. It is responsible for automatically calling webapp-config</tt> when the  USE flag is unset. In rare instances it may be desirable to override this behavior; please consult for an example.

Advanced: www-apps/moinmoin-1.5.0
This section presents an overview of more advanced installation tasks provided by. An example of this functionality is www-apps/moinmoin-1.5.0.

moinmoin</tt> is a wiki engine written in Python that uses distutils</tt> to install itself. Thus, it requires  to avoid collisions. Ebuilds that inherit must set   to override the default  ting behavior:

moinmoin</tt> installs files that should not be served by the web server. The ebuild places such files in.

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</tt>.

The reconfig hook is a script, typically written in bash, that is invoked by webapp-config</tt> after installation and before removal.

The reconfig hook can use the same variables as the post-install 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</tt>, reconfig hooks are run in a sandbox to minimize risk; please consult the man page 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 . Don't remove configuration files or any other files that may have been locally modified.

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

Apache

 * Be careful when installing Apache configuration files. If you place a misconfigured Apache configuration file into, 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.

Obtaining more information
Additional examples can be found in the 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 webapps team or ask in on Freenode.