Stuart Herbert

stuart@gentoo.org

stuart@gnqs.org

Renat Lumpau

rl03@gentoo.org

Gunnar Wrobel

wrobel@gentoo.org

Devan Franchini

twitch153@gentoo.org

2003-2015 Stuart Herbert Renat Lumpau Gunnar Wrobel Devan Franchini

July 2015 Gentoo Linux webapp-eclass 5 webapp-eclass standardised approach to writing ebuilds for web-based applications inherit webapp If you are writing an ebuild for a web-based application, your ebuild should use the functions, variables, and techniques documented in this man page. The main reason to use the webapp eclass is that it provides a solution to a number of problems that plagued older approaches: Many web servers today have to be able to host more than one website at a time. This is normally done through name-based virtual hosting. See the Apache documentation for more details about how this works. Traditional package installers only install a single copy of a package. Many webservers need to make the same package available as part of different virtual hosts. The administrator normally ends up installing and upgrading each of these packages by hand. This makes for more work for the administrator. webapp-eclass overcomes this problem by installing packages, and associated metadata, in a format and location understood by webapp-config8. The administrator then uses webapp-config to install and upgrade however many copies of the package as he needs. Virtual hosts are normally stored on disk in their own directories. The location of these directories can vary from computer to computer. It is not unusual for each administrator to have his own preferred location for putting virtual hosts. Traditional packagers always install a single copy of the package, normally into /home/httpd/htdocs/<package-name>/. If the administrator changes the DocumentRoot of their preferred web server to point to a different directory, traditional packagers are unable to detect this and adjust accordingly. They also are unable to detect any attempt to install a package into a virtual host. webapp-eclass overcomes this problem because it makes no attempt to install packages into the webserver's DocumentRoot. Instead, it installs the files of the package into the /usr/share/webapps hierarchy - which is never directly used by any webserver. The administrator then uses webapp-config to complete the installation to the directory of his choice. Web-based applications are made up of files and directories that need to be owned by more than one user. Any files or directories that the web server needs to write to - these need to be owned by whatever user the web server runs as. Configuration files need to be owned by the non-root user who owns the website. The rest of the files and directories need to be owned by root, to ensure that they cannot be tampered with by other users. Traditional packagers have no way to understand which user the web server runs as, or which user needs to own the configuration files. Some packages assume that the user is running the Apache web server, and hard-code the information into their installation scripts. Unfortunately, any packages that do this will not work if the user chooses to use an alternative web server. webapp-eclass overcomes this problem because it provides a number of functions which the ebuild can use to indicate who needs to own what. When the administrator completes the install using webapp-config, he can tell webapp-config which web server the package will be running under, and which user needs to own the configuration files. Most web-based applications are written in scripting languages such as PHP, Python, or Perl. Most scripting languages are available either as Apache modules and as stand-alone CGI scripting engines. Sometimes, it makes more sense to install scripting languages as CGI scripting engines. Although CGI engines run much slower than Apache modules, the advantage is that it allows a single computer to run multiple versions of the same language - something that sometimes is necessary. It's also worth pointing out that the administrator has a choice of web servers - and not all scripting languages run as compiled-in modules in all web servers. It is difficult-to-impossible for a traditional package manager to provide a single package that can cope with all of the possible permutations. webapp-eclass provides a function for ebuilds to indicate which script files need to be run by which scripting engine. webapp-config can, if necessary, modify these script files to use the correct CGI engine when installing into a virtual host. When packages are upgraded, new configuration files are installed. Different package managers handle this in different ways. Portage can prevent files being overwritten on a per-directory basis. Web-based applications normally have configuration files installed in the same directories as the scripts themselves. Packages for Portage, therefore, normally end up overwriting the configuration file because the alternative is having to wade through pages of etc-update output. webapp-eclass avoids this problem by allowing ebuilds to indicate which files are configuration files. webapp-config uses this information to ensure that configuration files are not overwritten. The administrator can then use etc-update as normal to complete the upgrade. There are some web-based applications that will not work without installing configuration files for the webserver. Deciding which webserver to install configuration files for, and where to install these configuration files, is problematic at best. webapp-eclass addresses this in two ways. Firstly, ebuilds are encouraged to supply configuration files for all supported webservers. webapp-config will then install the correct configuration files for the selected webserver when the virtual copy of the application is installed. Many web-based applications store their data in sql-based databases. Installing these databases is enough of a pain; upgrading them is something that's often left to the administrator to struggle through. webapp-eclass does not provide a full solution today to this problem. Ebuilds can indicate which files are SQL scripts, and which database engine the scripts are for. A future version of webapp-eclass will (hopefully) provide a tool to automatically generate an upgrade script to help the administrator. webapp-eclass creates an intermediate install of a package, so that the computer's administrator can then perform multiple installations using webapp-config8. The intermediate install (known as the master copy) is never used by, or accessed via, the web server. The intermediate install goes into the /usr/share/webapps directory structure: /usr/share/webapps |- <package name> |- <package version> |- hostroot ${MY_HOSTROOTDIR} |- htdocs ${MY_HTDOCSDIR} |- cgi-bin ${MY_CGIBINDIR} |- conf ${MY_SERVERCONFIGDIR} |- errors ${MY_ERRORSDIR} |- icons ${MY_ICONSDIR} MY_HOSTROOTDIR Any files or directories that would normally go into /var/www/localhost should be installed into this directory. This directory is for files that you do not want served up under the DocumentRoot. An example of suitable files would be password databases. MY_HTDOCSDIR Any files or directories that would normally go into /var/www/localhost/htdocs/<package-name>/ should be installed into this directory. This directory is for the main files of the package. Don't put all the files in a subdirectory called <package-name>. MY_CGIBINDIR Any files or directories that would normally go into /var/www/localhost/cgi-bin/ should be installed into this directory. At runtime (when the package is running), this directory will be read-only. You should keep this in mind when deciding which files, scripts, and executables belong in here. MY_SERVERCONFIGDIR This directory contains the per-vhost config files that the web server will use. You may have to manually configure your webserver to actually use any configuration files installed in this directory. MY_ERRORSDIR Any files or directories that would normally go into /var/www/localhost/errors/ should be installed into this directory. When the webserver encounters an error, such as 403: Forbidden or 404: File not found, the default behaviour of the webserver is to look for a page in the MY_ERRORSDIR directory. MY_ICONSDIR Any files or directories that would normally to into /var/www/localhost/icons/ should be installed into this directory. webapp_pkg_setup If your ebuild has a pkg_setup, make sure that the first thing it does is to call the webapp_pkg_setup function. This function performs a lot of sanity checks. The first line of your src_install() function must be webapp_src_preinst webapp_src_preinst() prepares ${D}, so that you can install your files into directories as normal. Then, use these functions after you have installed your files, to add metadata that webapp-config will use later. Unless explicitly stated in the description of the function, you should assume that these functions do not copy any files into ${D} for you. webapp_configfile file [file ...] Use this function to indicate that a particular file is an editable configuration file. webapp-config will install configuration files so that they can be edited by non-root users. file is a config-file. The file should be in ${D}. file is normally under ${MY_HTDOCSDIR}. webapp_hook_script file Use this function to install a script that webapp-config will run immediately after the creation of a virtual copy and immediately before the removal of a virtual copy. file is an executable script. The script must accept one parameter; either file install, or file clean. When called as file install, the script is running after the creation of a virtual copy. And when called as file clean, the script is running immediately before the removal of a virtual copy. Think of hook scripts as a way to perform custom actions that webapp-config itself doesn't give you a way to do. Because any files created by hook scripts aren't added to the contents list, it is essential that hook scripts also clean up after themselves - because webapp-config cannot do it for you. Hook scripts are now run inside a sandbox. Write access is limited to VHOST_HTDOCSDIR, MY_INSTALLDIR, VHOST_ROOT and VHOST_CGIBINDIR. Hook scripts can rely on a number of environment variables being set. They are listed in the HOOK SCRIPT VARS section below. Please note that hook scripts must work correctly with ${ROOT} set! webapp_postinst_txt language file Use this function to install a plain text file that contains any post-installation instructions that the administrator needs to read about. webapp-config will show these instructions to the administrator after he has run webapp-config -I. The instructions can contain shell variables. They will be expanded by webapp-config before being shown to the administrator. The instructions can make use of the environment variables that are listed in the HOOK SCRIPT VARS section below. language is for future compatibility. For now, always use en. file is a text file in ${S}. This function will install this file for you into ${D}. webapp_postupgrade_txt language file Use this function to install a plain text file that contains any post-uprade instructions that the administrator needs to read about. webapp-config will show these instructions to the administrator after he has run webapp-config -U. The instructions can contain shell variables. They will be expanded by webapp-config before being shown to the administrator. The instructions can make use of the environment variables that are listed in the HOOK SCRIPT VARS section below. language is for future compatibility. For now, always use en. file is a text file in ${S}. This function will install this file for you into ${D}. webapp_serverowned [-R] file [file ...] Use this function to mark a file that needs to be owned by whichever user the web server runs as. webapp-config will ensure that the file is owned by the correct user when the time comes. file is a file under ${D}. Use the optional -R flag to recurse into subdirectories. webapp_server_configfile server file newfile Use this function to install a webserver configuration file. The configuration file is installed into ${MY_SERVERCONFIGDIR}, and webapp-config will install this file during install (-I mode). server is one of: apache, lighttpd, cherokee. file is a webserver configuration file in ${S}. This should be a configuration file tested with server. newfile is the new name for file. This parameter is optional; if not supplied, newfile is set to `basename file`. webapp_sqlscript sql-engine file Use this function to install an SQL script. The script is installed into ${MY_SQLSCRIPTSDIR}, but is not installed into any database server at this time. sql-engine is one of: mysql, postgresql. file is an SQL script in ${S}. This should be a script to create the tables from scratch. file will be installed into ${D} for you by this function. webapp_src_install Call this function at the end of your src_install function. To see what this function does, read the source code. webapp_pkg_postinst If your ebuild has a pkg_postinst function, make sure the last thing it does is to call webapp_pkg_postinst. This function automatically calls webapp-config if the vhosts flag is NOT present. These environment variables will always be present whenever webapp-config runs a hook script, or whenever post-installation instructions are shown. MY_HOSTROOTDIR MY_HTDOCSDIR MY_CGIBINDIR MY_ERRORSDIR MY_ICONSDIR MY_SERVERCONFIGDIR MY_SQLSCRIPTSDIR See the Install Directories section above. ROOT The ${ROOT} variable as set by Portage. Please note that you do not need to explicitly add the ${ROOT} prefix - webapp-config will do that automatically. MY_INSTALLDIR The full path to the directory that the virtual copy has been installed into. If you are not using virtual hosts, this defaults to /var/www/localhost/htdocs/${PN}/. VHOST_SERVER The name of the webserver that we are installing for. Set with the -s option to webapp-config. At the moment, webapp-config only supports the apache-basic web server, so this isn't a lot of use. VHOST_ROOT The full path to the Document Root's parent directory. If you are not using virtual hosts, this defaults to /var/www/localhost/. VHOST_HOSTNAME The hostname that this application will be accessed via. If you are not using virtual hosts, this defaults to localhost. VHOST_HTDOCSDIR The full path to the Document Root of the website that the virtual copy is being installed into. If you are not using virtual hosts, this defaults to /var/www/localhost/htdocs/. VHOST_APPDIR The directory under VHOST_HTDOCSDIR where the virtual copy is being installed into. If you want the full path, use $MY_INSTALLDIR. VHOST_CGIBINDIR The directory under VHOST_HTDOCSDIR which cgi-bin files installed into. VHOST_CONFDIR The directory under VHOST_HTDOCSDIR which server configuration files are installed into. VHOST_ERRORSDIR The directory under VHOST_HTDOCSDIR which custom error files are installed into. VHOST_ICONSDIR The directory under VHOST_HTDOCSDIR which custom server icons are installed into. VHOST_CONFIG_UID The name of the user who owns all configuration files. VHOST_CONFIG_GID The name of the user who owns all configuration files. VHOST_SERVER_UID The name of the user who will own all server-owned files and directories. VHOST_SERVER_GID The name of the group who owns all server-owned files and directories. VHOST_DEFAULT_UID The name of the user who owns all the remaining files and directories. VHOST_DEFAULT_GID The name of the group who owns all the remaining files and directories. VHOST_PERMS_SERVEROWNED_DIR VHOST_PERMS_SERVEROWNED_FILE VHOST_PERMS_CONFIGOWNED_DIR VHOST_PERMS_CONFIGOWNED_FILE VHOST_PERMS_DEFAULTOWNED_DIR VHOST_PERMS_VIRTUALOWNED_DIR VHOST_PERMS_VIRTUALOWNED_FILE VHOST_PERMS_INSTALLDIR See webapp-config5 for details. See /usr/share/doc/webapp-config*/ for example ebuilds. /etc/vhosts/webapp-config Configuration file, holding the defaults for webapp-config and the webapp-eclass eclass. webapp-config5, webapp-config8, emerge1 The webapp-eclass is part of the webapp-config package. webapp-config is based on the design for an installer for web-based applications first discussed in GLEP #11 for the Gentoo Linux project.