Webapp-config

webapp-config is Gentoo's installer for web-based applications. It is used for automatic setup of web applications in virtual hosting environments. Originally written as a bash script, webapp-config is now Python-based and available in the Portage tree.

Concepts
webapp-config is aimed at providing the package management functionality that web server administrators need when running multiple web sites off of the same IP address (virtual hosting).

Two-stage install
Package managers such as RPM and Portage are designed to install one copy of a package, and to install it onto a fixed location. This conflicts with the needs of a virtual hosting environment, where administrators need to be able to install one package in multiple places so that it can be part of more than one website. With that being said, package managers are essential for maintaining an operating system over time - how is it possible to have the best of both worlds?

The answer is a two-stage install. The traditional package manager installs a master copy into This master copy is not fit to run - but it is ready to be used by the webapp-config utility to install a single package multiple times in multiple places.

Multiple installations of the same package
webapp-config allows the administrator to install multiple copies of the same package on the same system at the same time. The administrator decides which directories to install each copy into.

In the web application world, these multiple installations are called "virtual copies".

Different versions of the same package can be installed on the same system at the same time. This allows web administrators to gradually roll out a new version of a package across sites; they are not forced to upgrade every site at once.

webapp-config minimizes the number of duplicated files to the absolute minimum. This keeps disk space usage low. The majority of files are hard linked to the master copy; only configuration files, and any files that the package needs to write to are copied into the virtual copy.

File ownership and permissions
Administrators who are used to installing web-based applications by hand will know that it can be a pain to get every file owned by the correct user, and with the correct permissions. Some files need to be owned by the user that the web server runs as. Others need to be owned by specific shell accounts, so that those users can login and edit the configuration files. If the Linux distribution offers a choice of web servers - each running under a different user - even the installers can struggle to get it right.

With webapp-config, the administrator tells the installer which web server to use and which shell account needs to be able to edit the configuration files. webapp-config then installs the files with the correct ownership and permissions.

Protected configuration files
webapp-config</tt> automatically ensures that configuration files are never overwritten during an upgrade - even if the files have not edited since the original installation. Additionally, webapp-config</tt> will never overwrite any file that it did not install, or that has been changed since it was installed by webapp-config</tt>. webapp-config</tt> uses MD5 check sums to determine whether a file has been changed or not. In the case of symbolic links, webapp-config</tt> will not replace a symlink that points to a different file.

When an upgrade does attempt to overwrite a protected file, webapp-config</tt> creates a file with the new file inside. etc-update</tt> can be used to complete the install, just as a regular emerge</tt>.

File copying options
A virtual copy is built mostly by creating hard links to files under. If a hard link cannot be created, the file is copied from instead.

Hard links can only be created to files on the same filesystem. If and  on kept on different filesystems, webapp-config</tt> cannot use hard links, and will be forced to copy the files instead.

There are three ways to get around the hard link problem.

The easiest way is to make a symlink to a directory under. For most administrators, this will ensure that everything is on the same filesystem.

However, if the hosted websites are kept on separate filesystems, then webapp-config</tt> is never going to be able to hard-link files.

As an alternative the  command-line option can be used. This tells webapp-config</tt> to create symbolic links instead of hard links. Symbolic links work across filesystems.

The problem with using symbolic links is that some packages do not work when the virtual copy is made from symbolic links. Many users - and system administrators alas - have also complained that they find directories full of symbolic links confusing. For these reasons, symbolic links are not used by default in webapp-config</tt> any more.

The  command-line option can also be chosen. This particular switch tells webapp-config</tt> to directly copy the files from instead of hard links. Copying directly works across filesystems with the drawback of using more space but if you are going to use it across file systems you may want this instead of symbolic links, as this means that the files in will not be touched when the files in the location of the virtualhost are altered.

Virtual file voodoo
By default, the master copy contains the metadata that decides which files get linked into a virtual copy and which files do not. Files are either owned by the web server (server-owned), are configuration files (config-owned), or are linked in (virtual). Directories can be server-owned or config-owned, but most of the time they need to be just plain directories (default-owned) created inside the installation directory (set with the  option). webapp-config</tt> provides a number of switches which allows for overriding the master copy's metadata - in the case the overriding is ever needed.

The  and   switches allow the administrator to decide what webapp-config</tt> will do if (respectively) a directory or a file is marked as being default or virtual. webapp-config</tt> can be instructed to make the directory or file any of the other choices - server-owned or config-owned - instead.

${ROOT}
<tt>webapp-config</tt> is intended to fully support. For administrators unsure what that means see the emerge man page (<tt>man emerge</tt>).

Features
Using the  USE flag <tt>webapp-config</tt> is capable of managing the following applications:

Emerge
Install <tt>webapp-config</tt>:

Web server setup
<tt>webapp-config</tt> needs to know which web server to host the installed applications with. Popular choices include:


 * Apache
 * Lighttpd
 * Nginx

Edit the following line in the file to set a web server. This example would be the correct modification to make if <tt>lighttpd</tt> was the web server of choice:

Actions

 * <tt>-I, --install</tt>
 * Activate install mode.


 * <tt>-U, --upgrade</tt>
 * Activate upgrade mode.


 * <tt>-C, --clean</tt>
 * Activate remove mode.

Examples
To install a webapp:

To list installed webapps:

To show installed webapps:

To update a previously installed webapp:

To remove an installed webapp:

Ghost installs
Entries still exist when running <tt>webapp-config --list-installs</tt> when the files in directory have been deleted.

The trouble probably was generated from an improper deletion of a webapp. If the files in are manually deleted then the <tt>webapp-config</tt> program can become confused. Uninstalls should be managed by running <tt>webapp-config -C <application_name></tt>.

Uninstall webapp-config:

Once removed, delete any left over installation files that may be found in the directory.

Reinstall <tt>webapp-config</tt> and run the command with the. All ghost installs should be gone.