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. Using the webapp-config utility is beyond the scope of this guide and is documented in man 8 webapp-config.
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.
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, webapp.eclass will be found under /var/db/repos/gentoo/eclass/. 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 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.
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 man page). #doc_chap2_sect3 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 the src_unpack or src_compile function; installation is handled in the src_install function. 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 web server's document root by webapp-config. For a full list of variables exported by the eclass, please see the man page.
Next, the ebuild marks a file in the 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
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 understand the important difference in usage. More often than not, post-install instructions include information specific to a virtual host, such as locations of a particular configuration file or a URL to access the web application remotely. This information is not available to Portage and cannot be included in pkg_postinst. Instead, it should be included in a post-install file and installed using webapp_postinstall_txt.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 man page 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.
If the package requires specific Perl modules, all dependencies must have ebuilds available. Relying on CPAN is not acceptable.
A common mistake with specifying dependencies for web applications is to 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, the ebuild should never explicitly RDEPEND on a database such as dev-db/mysql or dev-db/postgresql. Instead, consider RDEPENDing on the appropriate language bindings.
Carefully consider whether the web application needs Apache (www-servers/apache), or if it can work with a generic web server. Consider using virtual/httpd-basic , virtual/httpd-cgi, or virtual/httpd-fastcgi instead.
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 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 /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"
The
yes is case-sensitive.moinmoin installs files that should not be served by the web server. 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 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, 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
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.
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.
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 webapps team or ask in #gentoo-web (webchat) on Libera.Chat.
This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Renat Lumpau
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.