diff options
author | Anthony G. Basile <blueness@gentoo.org> | 2012-06-27 20:37:22 -0400 |
---|---|---|
committer | Anthony G. Basile <blueness@gentoo.org> | 2012-06-27 20:37:22 -0400 |
commit | 94f241acb9a3998c1ea41fe74a44091b1dff72eb (patch) | |
tree | 99331de324ce870386146ecfef3c438901585291 /doc | |
parent | Remove examples (diff) | |
download | webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.gz webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.bz2 webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.zip |
Clean up doc, readdress gentoo bug #322759
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile | 4 | ||||
-rw-r--r-- | doc/webapp-eclass.5.xml (renamed from doc/webapp.eclass.5.xml) | 0 | ||||
-rw-r--r-- | doc/webapp-eclass.xml | 567 |
3 files changed, 2 insertions, 569 deletions
diff --git a/doc/Makefile b/doc/Makefile index aaace8a..4dc8e44 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -14,8 +14,8 @@ # # ======================================================================== -MAN_PAGES = webapp-config.8 webapp-config.5 webapp.eclass.5 -HTML_PAGES = webapp-config.8.html webapp-config.5.html webapp.eclass.5.html +MAN_PAGES = webapp-config.8 webapp-config.5 webapp-eclass.5 +HTML_PAGES = webapp-config.8.html webapp-config.5.html webapp-eclass.5.html TMPFILE=./webapp-config.man diff --git a/doc/webapp.eclass.5.xml b/doc/webapp-eclass.5.xml index f310f56..f310f56 100644 --- a/doc/webapp.eclass.5.xml +++ b/doc/webapp-eclass.5.xml diff --git a/doc/webapp-eclass.xml b/doc/webapp-eclass.xml deleted file mode 100644 index 569b353..0000000 --- a/doc/webapp-eclass.xml +++ /dev/null @@ -1,567 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/webapps/webapp-eclass.xml,v 1.3 2006/01/19 16:43:24 rl03 Exp $ --> - -<guide link="/proj/en/webapps/webapp-eclass.xml" lang="en"> -<title>webapp.eclass Documentation</title> - -<author title="Author"> - <mail link="rl03@gentoo.org">Renat Lumpau</mail> -</author> - -<abstract> -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 complexity and functionality. -</abstract> - -<!-- The content of this document is licensed under the CC-BY-SA license --> -<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> -<license/> - -<version>1.0</version> -<date>2006-01-17</date> - -<chapter> -<title>Introduction</title> -<section> -<title>Background</title> -<body> - -<p> -<c>webapp.eclass</c> and <c>webapp-config</c> provide a standardized way to -maintain web applications on Gentoo. Server administrators can use the -<c>webapp-config</c> utility to install, upgrade, and remove software. -<c>webapp-config</c> relies on a package manager such as Portage to prepare -the application for installation into multiple virtual hosts. On Gentoo, this -is done by an ebuild that uses <c>webapp.eclass</c>. -</p> - -<p> -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 -<c>webapp.eclass</c> and then discusses three ebuilds of increasing complexity -and functionality. Using the <c>webapp-config</c> utility is beyond the scope -of this guide and is documented in <c>man 8 webapp-config</c>. -</p> - -</body> -</section> -<section> -<title>Prerequisites</title> -<body> - -<p> -This guide assumes a basic familiarity with Portage and the ebuild format. Both -are well-documented; the reader is encouraged to consult the <uri -link="/proj/en/devrel/handbook/handbook.xml">official ebuild HOWTO</uri> and -the unofficial <uri -link="http://dev.gentoo.org/~plasmaroo/devmanual/">devmanual</uri>. -</p> - -<p> -<c>webapp-config</c> 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 the -development process on our <uri -link="http://www.vhost-tools.org/">website</uri>. -</p> - -</body> -</section> -<section> -<title>A standardized approach to installing web applications</title> -<body> - -<p> -Gentoo has developed a standardized way of handling web applications. It is -outlined in <uri link="/proj/en/glep/glep-0011.html">GLEP 11</uri> and -discussed in detail in <c>man 5 webapp.eclass</c>. The reader is urged to -familiarize himself with these documents before proceeding. The manpage also -outlines the filesystem locations into which the eclass and -<c>webapp-config</c> install files; advanced users and developers should take -note. -</p> - -<p> -The <c>webapp.eclass</c> is located in the usual place in the Portage tree. By -default, it will be found in <path>/usr/portage/eclass/webapp.eclass</path>. 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. -</p> -</body> -</section> -</chapter> - -<chapter> -<title>Writing Ebuilds</title> -<section> -<title>Beginner: www-apps/gallery-2.0.2</title> -<body> - -<p> -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. The -<c>webapp.eclass</c> simplifies this task by preparing the necessary set of -directories. -</p> - -<p> -Let's take a look at a simple ebuild for <uri -link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/gallery">www-apps/gallery-2.0.2</uri>. -To use any of the functions in the eclass, the ebuild must first inherit it: -</p> - -<pre caption="Inheriting the eclass"> -inherit webapp.eclass -</pre> - -<p> -The ebuild then sets several standard variables, such as <c>DESCRIPTION</c>, -<c>IUSE</c>, <c>RDEPEND</c>, and <c>S</c>. The first important note is that -ebuilds that use the <c>webapp.eclass</c> do not typically set the <c>SLOT</c> -variable (the rationale for this is described in the manpage). <uri -link="#doc_chap2_sect3">Section 2.3</uri> will explain how <c>SLOT</c> can be -set when it is truly needed, but for now we will let the eclass handle it. -</p> - -<note> -Unless explicitly overridden, the eclass sets <c>SLOT="${PVR}"</c>. One -important downside of this behavior is that security revision bumps are no -longer possible. This is unfortunate and will be changed soon. -</note> - -<p> -<path>www-apps/gallery-2.0.2</path> does not require patching or compiling, so -the ebuild does not call <c>src_unpack</c> or <c>src_compile</c>; installation -is handled in <c>src_install</c>. The first thing <c>src_install</c> does is -call a special helper function that sets up the required directory structure: -</p> - -<pre caption="Setting up src_install"> -src_install() { - webapp_src_preinst -</pre> - -<p> -This function is required of all ebuilds that use the <c>webapp.eclass</c> and -override the default <c>src_install</c>. -</p> - -<p> -Having set up the environment, the ebuild installs the web application: -</p> - -<pre caption="Installing"> -cp -R * ${D}/${MY_HTDOCSDIR} -</pre> - -<p> -<c>${MY_HTDOCSDIR}</c> is one of the variables exported by -<c>webapp_src_preinst</c>. Files placed there will be copied into the right -directory under the webserver's document root by <c>webapp-config</c>. For a -full list of variables exported by the eclass, please see the manpage. -</p> - -<p> -Next, the ebuild marks a file in <c>${FILESDIR}</c> as a file containing -instructions to be displayed by <c>webapp-config</c> after the application has -been installed: -</p> - -<pre caption="Post-install instructions"> -webapp_postinst_txt en ${FILESDIR}/postinstall-en2.txt -</pre> - -<note> -A careful reader will observe that it is customary for other ebuilds to display -instructions to the user in <c>pkg_postinst</c>. Ebuilds that inherit -<c>webapp.eclass</c> 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 <c>pkg_postinst</c>. Instead, it should be included in a post-install file -and installed using <c>webapp_postinstall_txt</c>. -</note> - -<p> -Let's examine a typical post-install file: -</p> - -<pre caption="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! -</pre> - -<p> -Post-install instruction files are plain text files. They can contain -bash-style variables (e.g., <c>${PN}</c>) that will be expanded at display -time. The <c>webapp-config</c> 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. -</p> - -<p> -Finally, the ebuild calls another mandatory helper function: -</p> - -<pre caption="webapp_src_install"> -webapp_src_install -</pre> - -<p> -<c>webapp_src_install</c> is responsible for setting the right permissions on -installed files. -</p> - -<p> -There are several best practices for writing simple ebuilds: -</p> - -<ul> - <li> - Don't copy unneeded files. Some packages include <path>.svn</path> or - <path>CVS</path> directories or <path>Makefiles</path>; those should be - removed prior to installation. Note that the <path>LICENSE</path> file is - sometimes needed by the application and should not be removed. - </li> - <li> - Ensure that consecutive calls to all ebuild functions succeed. For - instance, don't remove files outside of <c>src_unpack</c>. If you must, - remove files from <c>${D}</c> rather than <c>${S}</c>. - </li> - <li> - For portability purposes, don't use GNU-only extensions such as <c>cp - -a</c>. They will break on non-GNU userlands such as Gentoo/FreeBSD. - </li> -</ul> - -</body> -</section> -<section> -<title>Intermediate: www-apps/tikiwiki-1.9.2</title> -<body> - -<p> -Many web applications have a more complicated installation procedure. Let's -look at how <uri -link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/tikiwiki">www-apps/tikiwiki-1.9.2</uri> -handles one such package. After inheriting the eclass, the ebuild specifies a -number of required and optional dependencies. -</p> - -<pre caption="Specifying Dependencies"> -RDEPEND="virtual/php - mysql? ( >=dev-db/mysql-4 ) - postgres? ( dev-db/postgresql ) - graphviz? ( media-gfx/graphviz ) -" -</pre> - -<p> -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 -<c>depend.php</c> eclass; unfortunately, the author is not aware of any existing -documentation for that eclass. The reader is referred to the eclass itself for -further information and encouraged to consult relevant ebuilds in Portage. -</p> - -<warn> -If the package requires specific Perl modules, all dependencies must have -ebuilds available. Relying on CPAN is not acceptable. -</warn> - -<p> -A common mistake with specifying dependencies for web applications is to -unconditionally <c>RDEPEND</c> 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: -</p> - -<pre caption="Database Dependencies"> -mysql? ( >=dev-db/mysql-4 ) -</pre> - -<note> -It is currently not possible to depend on a generic webserver. Instead, you -must explicitly specify the webserver (e.g., <path>net-www/apache</path>). This -is inconvenient and has been reported in <uri -link="http://bugs.gentoo.org/show_bug.cgi?id=11007">bug #11007</uri>; we hope -that this issue will be resolved soon. -</note> - -<p> -<path>www-apps/tikiwiki</path> does not use <c>depend.php</c> and instead uses -<c>pkg_setup</c> to print a warning: -</p> - -<pre caption="pkg_setup()"> -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" -} -</pre> - -<p> -Note the use of a mandatory helper function <c>webapp_pkg_setup</c>. -</p> - -<p> -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, -<c>webapp-config</c> will ensure that it has the right owner and permissions: -</p> - -<pre caption="webapp_serverowned"> -webapp_serverowned ${MY_HTDOCSDIR}/tiki-install.php -</pre> - -<p> -<c>webapp_serverowned</c> takes an optional <c>-R</c> 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. -</p> - -<p> -Practically all web applications use configuration files to store settings. -Such files should not be placed into <path>/etc</path> (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 <c>webapp-config</c> not to overwrite an existing file. The -administrator can use familiar tools such as <c>etc-update</c> or -<c>dispatch-conf</c> to manage such files. -</p> - -<pre caption="webapp_configfile"> -webapp_configfile ${MY_HTDOCSDIR}/config.php -</pre> - -<p> -Note that it is currently not possible to mark a file as both server-owned and -config-protected. This has been fixed in an upcoming version of -<c>webapp-config</c>. For now, there is a workaround described in <uri -link="#doc_chap2_sect3">Section 2.3</uri>. -</p> - -<p> -To ease upgrades of web applications, the eclass provides a helper function -that displays instructions when an existing installation is being upgraded: -</p> - -<pre caption="Post-upgrade file"> -webapp_postupgrade_txt en ${FILESDIR}/postupgrade-en.txt -</pre> - -<p> -Even though no ebuilds in Portage currently take advantage this functionality, -the reader is encouraged to use it in his ebuilds. -</p> - -<p> -The ebuild calls the familiar helper function to complete the installation. -Note an important consequence of using <c>webapp_src_install</c> to set the -correct file permissions: any manual adjustments to file permissions and -ownership via <c>fowners</c> and <c>fperms</c> must occur <e>after</e> -<c>webapp_src_install</c> is called. -</p> - -<pre caption="Adjusting permissions"> -webapp_src_install -fperms 0644 /etc/zm.conf -</pre> - -<p> -The tikiwiki ebuild displays some brief notes using <c>pkg_postinst</c>. Note -the use of another helper function: -</p> - -<pre caption="pkg_postinst"> -pkg_postinst() { - einfo "To setup a MySQL database, run:" - einfo "\"emerge --config =${PF}\"" - einfo "If you are using PostgreSQL, consult your documentation" - webapp_pkg_postinst -} -</pre> - -<p> -Strictly speaking, <c>webapp_pkg_postinst</c> is not mandatory. It is -responsible for automatically calling <c>webapp-config</c> when the -<c>vhosts</c> USE flag is unset. In rare instances it may be desirable to -override this behavior; please consult <path>www-apps/otrs</path> for an -example. -</p> - -</body> -</section> -<section> -<title>Advanced: www-apps/moinmoin-1.5.0</title> -<body> - -<p> -This section presents an overview of more advanced installation tasks provided -by the <c>webapp.eclass</c>. An example of this functionality is <uri -link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/moinmoin">www-apps/moinmoin-1.5.0</uri>. -</p> - -<p> -<c>moinmoin</c> is a wiki engine written in Python that uses <c>distutils</c> -to install itself. Thus, it requires <c>SLOT="0"</c> to avoid collisions. -Ebuilds that inherit <c>webapp.eclass</c> must set -<c>WEBAPP_MANUAL_SLOT="yes"</c> to override the default <c>SLOT</c>ting -behavior: -</p> - -<pre caption="Setting SLOT"> -SLOT="0" -WEBAPP_MANUAL_SLOT="yes" -</pre> - -<note> -The <c>yes</c> in <c>WEBAPP_MANUAL_SLOT="yes"</c> is case-sensitive. -</note> - -<p> -<c>moinmoin</c> installs files that should not be served by the webserver. The -ebuild places such files in <c>${MY_HOSTROOTDIR}/${PF}</c>. -</p> - -<pre caption="Installing into dodir ${MY_HOSTROOTDIR}/${PF}"> -dodir ${MY_HOSTROOTDIR}/${PF} -cp -r data underlay config/wikiconfig.py ${D}/${MY_HOSTROOTDIR}/${PF} -</pre> - -<p> -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 <c>webapp-config</c>. -</p> - -<pre caption="webapp_hook_script"> -webapp_hook_script ${FILESDIR}/reconfig-2 -</pre> - -<p> -The reconfig hook is a script, typically written in bash, that is invoked by -<c>webapp-config</c> after installation and before removal. -</p> - -<pre caption="Reconfig hook"> -#!/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 -</pre> - -<p> -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 <c>webapp-config-1.50</c>, reconfig hooks -are run in a sandbox to minimize risk; please consult the manpage for more -details. -</p> - -<p> -There are several best practices for using reconfig hooks: -</p> - -<ul> - <li>Die with an error message if the script failed</li> - <li> - Be careful about removing files when called with <c>clean</c>. Don't remove - configuration files or any other files that may have been locally - modified. - </li> - <li> - To mark a file as both config-protected and server-owned, use - <c>webapp_configfile</c> from the ebuild and use the reconfig hook to mark - it as server-owned: - </li> -</ul> - -<pre caption="Using the reconfig hook to mark files as server-owned"> -chown ${VHOST_SERVER_UID}:${VHOST_SERVER_GID} ${MY_INSTALLDIR}/Settings.php -</pre> - -<p> -The eclass provides several other functions that are rarely used. The most -notable is <c>webapp_sqlscript</c>, which marks a file as an SQL create script. -In its current state, this function is only moderately useful. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Additional Best Practices</title> -<section> -<title>Apache</title> -<body> - -<ul> - <li> - Be careful when installing apache configuration files. If you place a - misconfigured Apache configuration file into - <path>/etc/apache{2}/vhosts.d</path>, 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. - </li> -</ul> - -</body> -</section> -</chapter> - -<chapter> -<title>Next Steps</title> -<section> -<title>Obtaining More Information</title> -<body> - -<p> -Additional examples can be found in the <path>www-apps</path> category of the -Portage tree. Developers and users should also consult the <uri -link="http://svn.gnqs.org/projects/gentoo-webapps-overlay">web-apps -overlay</uri> for even more examples and software packages. -</p> - -<p> -If you have a question that is not answered in this document, please feel free -to contact the <uri -link="http://svn.gnqs.org/projects/gentoo-webapps-overlay/wiki/Contributors">web-apps -herd</uri> or ask on <uri link="irc://freenode/gentoo-web">IRC</uri>. -</p> - -</body> -</section> -</chapter> -</guide> |