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 webapp.eclass and then discusses three ebuilds of increasing complexity and functionality.

Background
and provide a standardized way to maintain web applications in Gentoo. Server administrators can use the utility to install, upgrade, and remove software. 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.

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  utility is beyond the scope of this guide and is documented in.

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.

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. The reader is urged to familiarize himself with these documents before proceeding. The manpage also outlines the filesystem locations into which the eclass and  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.

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:

Inheriting the eclass

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 manpage). 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:

{{Code|Setting up src_install| 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:

Installing

is one of the variables exported by. Files placed there will be copied into the right directory under the webserver's document root by. For a full list of variables exported by the eclass, please see the manpage.

Next, the ebuild marks a file in  as a file containing instructions to be displayed by   after the application has been installed:

Post-install instructions

Let's examine a typical post-install file:

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

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

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

Checking PHP configuration

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

webapp_serverowned

takes an optional 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 (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  not to overwrite an existing file. The administrator can use familiar tools such as  or   to manage such files.

webapp_configfile

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

Post-upgrade file

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.

Adjusting permissions

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

pkg_postinst

Strictly speaking,  is not mandatory. It is responsible for automatically calling  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.

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

Setting SLOT

installs files that should not be served by the webserver. The ebuild places such files in.

Installing into dodir ${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_hook_script

The reconfig hook is a script, typically written in bash, that is invoked by  after installation and before removal.

Reconfig hook

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 , 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  . Don't remove configuration files or any other files that may have been locally modified.

Using the reconfig hook to mark files as server-owned

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 web-apps team or ask in #gentoo-web on Freenode.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Renat Lumpau