Webapp-config

General

• webapp-config is a Gentoo only tool to allow a single web applications to be correctly installed into multiple virtual hosts. This is nice as it allows the code to remain on a standard, Portage managed place while you can easily deploy your web applications into production.

• Currently the way it works is by creating a directory corresponding to the application inside the specified virtual host. By default it will be installed in /var/www/<virtual_host_name>/htdocs; you can configure that by editing /etc/vhosts/webapp-config. I use the following convention:

vhost_root="/srv/${vhost_subdomain_2}.${vhost_subdomain_1}/"
vhost_htdocs_insecure="./"

• In /etc/vhosts/webapp-config, you need to have a vhost_hostname variable that can conform to a fully qualified domain, eg localhost won't work. Put something like "elvanor.net" there.

• The only problem is that webapp-config always creates icons, error, and cgi-bin directories in the virtual host directory if they are not there. I would prefer that not to happen.

Hard linked files

• By default, webapp-config does not copy files from the master installation (what the ebuild installs in /usr/share/webapps/), but hard links files to their originals. I don't think this is a good thing; it saves very few space and can conflict with the dependency management systems of the web applications, if you have several installations of the same package. For instance, Mediawiki uses Composer (PHP dependency management system) and you may need to run Composer inside the webapp directory to install extensions (or even fix missing dependencies). If you have several installations of Mediawiki, some original files will get overwritten and the changes will apply to all installations, breaking things.
• To avoid that, use the -c flag when installing the webapp so that files are copied and not hard linked. Each time you have a "modern" dependency manager that installs stuff locally (such as Composer or npm), it's better to keep installations entirely independent and separated.

Installing, checking

• Typical installation:

webapp-config -h shoopz.com -d wordpress -I wordpress 2.7.1
webapp-config -c -h elvanor.net -d mediawiki -U mediawiki 1.35.1

• To check what are the current installations of a given application (you can optionally specify a version):

webapp-config --list-installs wordpress 2.8

• To check the application and version installed on a directory:

webapp-config --show-installed -h elvanor.net -d owncloud

• To list all installs:

webapp-config -li "*"

• To check unused installs (very useful):

webapp-config --lui wordpress

Updating

• When you need to update a web application, use the -U switch, eg:

webapp-config -h elvanor.net -d phpmyadmin -U phpmyadmin 2.11.5

• If you use a directory different that the application name, don't forget to change that. However note that by convention that should not happen.

webapp-config -h www.elvanor.net -d www/mediawiki -U mediawiki 1.13.3

Important warnings

• Updating a web-application can sometimes remove the configuration files! Be sure to systematically check (this is the case with Wordpress, although it seems to be a bug). Also, any changes to the DB must usually be done manually.
• emerge --depclean will remove *installed* versions of a webapp package if a newer one has been already merged! Thus update all your web-applications before running emerge --depclean.
• Running webapp-cleaner should also be done before emerge --depclean.
• On the version of the web application, you must not omit any Gentoo specific -rX (for instance, 1.27.1-r1).

Cleaning

• The application webapp-cleaner can be used to remove old versions of an webapp package.
• Manual removal of a web-app (there may be some leftover files):

webapp-config -C -h shoopz.net -d bugzilla bugzilla 3.0.5