WEBAPP\-CONFIG

WEB-BASED APPLICATIONS AND VIRTUAL HOSTS

webapp-config is aimed at providing the package management functionality that you need if you are running multiple web sites off of the same computer (virtual hosting).  

Two-Stage Install

Package managers such as rpm and emerge are designed to install one copy of a package, and to install it onto one fixed location. This conflicts with the needs of a virtual hosting environment, where you need to be able to install a package in multiple places, so that it can be part of more than just the one website. But package managers are essential for maintaining a computer over time - so how can we have both?

The answer is a two-stage install. The traditional package manager installs a master copy into /usr/share/webapps/. This master copy isn't fit to run - but it is ready to then be used by webapp-config to install the package multiple times in multiple places.  

Multiple Installations Of The Same Package

webapp-config allows you to install multiple copies of the same package on the same computer at the same time. You choose which directory to install each separate copy into.

We call these multiple installations "virtual copies".

You can also have different versions of the same package installed at the same time. This allows you to gradually roll out a new version of a package across your sites; you are not forced to upgrade every single website at once.

webapp-config minimises the number of duplicated files to the absolute minimum possible, to keep 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

If you are used to installing web-based applications by hand, you'll appreciate 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 webserver runs as. Others need to be owned by specific shell accounts, so that those users can login and edit the configuration files. If your Linux distribution offers you a choice of web servers - each running under a different user - even the installers can struggle to get it right.

With webapp-config, you tell the installer which web server you are going to be using, and which shell account needs to be able to edit the configuration files. webapp-config then installs your files with the correct ownership and permissions.  

Protected Configuration Files

webapp-config automatically ensures that your configuration files are never overwritten during an upgrade - even if you have not edited the files at all. Additionally, webapp-config will never overwrite any file that it did not install, or that has been changed since it was installed by webapp-config. webapp-config uses md5 checksums to determine whether a file has been changed or not. In the case of symbolic links, webapp-config will not replace a symlink that points to a different file.

When an upgrade does attempt to overwrite a protected file, webapp-config creates a ._cfg file with the new file inside. You can use etc-update to complete the install, just as you would with the regular emerge.  

File Copying Options

A virtual copy is built mostly by creating hard links to files under /usr/share/webapps. If a hard link cannot be created, the file is copied from /usr/share/webapps instead.

Hard links can only be created to files on the same filesystem. If you keep /usr/share/webapps and /var/www on different filesystems, webapp-config 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 /usr/share/webapps a symlink to a directory under /var/www. For most people, this will ensure that everything is on the same filesystem.

However, if you keep the websites you host on separate filesystems (like I do), then webapp-config is never going to be able to hard-link files for you.

As an alternative you can choose to use the --soft command-line switch. This switch tells webapp-config 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 any more.

You may also choose the --copy command-line switch. This particular switch tells webapp-config to directly copy the files from /usr/share/webapps/ 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 /usr/share/webapps/ will not be touched when the files in the location of your 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-ownedor config-owned, but most of the time they need to be just plain directories (default-owned) created inside the installation directory (set with the -d switch). webapp-config provides a number of switches which allows you to override the master copy's metadata - if you ever find that you need to.

The --default-dirs and --virtual-files switches allow you to decide what webapp-config will do if (respectively) a directory or a file is marked as being default or virtual. You can tell webapp-config to make the directory or file any of the other choices - server-owned or config-owned - instead.  

${ROOT}

This version of webapp-config is intended to fully support ${ROOT}. If you are unsure what that means, consult emerge(1)  

ACTIONS

-I app-name app-version, --install app-name app-version

Activate install mode.

-U app-name app-version, --upgrade app-name app-version

Activate upgrade mode.

-C app-name app-version, --clean app-name app-version

Activate remove mode.

-li app-name app-version, --list-installs app-name app-version

Outputs a list of all the virtual copies of the app-name-app-version package.

If you omit app-name or app-version webapp-config will display all available packages/versions.

-lui app-name app-version, --list-unused-installs app-name app-version

Outputs a list of all the master copies of the app-name-app-version package that have not been installed using webapp-config -I.

-pd action, --prune-database action

Cleans up the installed webapps database for lingering uninstalled webapps. Behavior is determined by the action given.

action must be one of:

pretend

Shows output of what would be cleaned from the database

clean

Removes webapp entries that are not installed on the system

-si, --show-installed

Outputs the app-name and app-version of the application installed in directory.

Use the -d switch to tell webapp-config which directory to look in. directory is a directory under the htdocs dir.

-spi app-name app-version, --show-postinst app-name app-version

Displays the post-installation instructions of the app-name-app-version package. Very handy if you didn't see them displayed when the package was installed.

-spu app-name app-version, --show-postupgrade app-name app-version

Displays the post-upgrade instructions of the app-name-app-version package. Very handy if you didn't see them displayed when the package was upgraded.

-ls, --list-servers

Outputs a list of the web servers that webapp-config currently supports.

Use the -s server switch to change which web-server an install or upgrade should use.

-?, --help

Provide a list of supported switches. Also lists all the default values for each switch.

-v, --version

Displays the current version number of webapp-config

OPTIONS

List of the remaining switches that webapp-config accepts. To see the default values that webapp-config will use when a switch is omitted, use webapp-config --help.

app-name app-version

Together, these two parameters tell webapp-config which package to install (-I mode), upgrade to (-U mode), or to search for (--list-installs mode).

They must be the last two parameters passed to webapp-config.

These parameters are not optional.

--bug-report, --pretend, -p

Provide output to include inside a bug-report.

Use this switch if you're having problems with the install (-I mode), upgrade (-U mode), or clean (-C mode) operations. Add this switch to the command-line that's not working, and make sure you paste the output into your bug report.

If you need to use this switch, make sure it's the first switch you use to call webapp-config.

-s server, --server server

Set which web-server to install (-I mode) or upgrade (-U mode) for.

webapp-config needs to know which web server you are going to use to access your virtual copy. If you don't provide the correct switch, your virtual copy may not work correctly.

Use webapp-config --list-servers to see a list of valid server settings.

-u user, --user user

Set which user will own any installed configuration files.

When webapp-apache creates a virtual copy (-I mode), the virtual copy creates local copies of any configuration files that the package needs to use. By using the -u switch, you can specify which user owns these configuration files.

If you give shell accounts out to the users who host websites on your computer, the -u allows you to give ownership of the configuration file (and therefore write permission) to the shell account associated with the website.

user can be a username or a numerical user id.

-g group, --group group

Set which group will own any installed configuration files.

When webapp-apache creates a virtual copy (-I mode), the virtual copy creates local copies of any configuration files that the package needs to use. By using the -g switch, you can specify which group owns these configuration files.

If you give shell accounts out to groups of users who host websites on your computer, the -g allows you to give ownership of the configuration file (and therefore write permission) to the group associated with the website.

group can be a group name or a numerical group id.

-d directory, --dir directory

Specify where to create the virtual copy.

The webapp-config tool allows you to create a virtual copy anywhere you want. You are no longer limited to installing a web-based app in /home/httpd/htdocs/<package-name>/! Simply use the -d switch to tell webapp-config where you want to create your virtual copy.

directory is a directory under your htdocs dir. If you do not set the hostname correctly (by using the -h switch), webapp-config will look under the wrong htdocs directory!

This option is required by the -C switch.

-h host, --host host

Specify the fully-qualified domain name of the virtual host.

Some web-based applications - whether through genuine need or bad design - need to know the hostname of the website that they are part of.

Some web-based applications need to install files (such as cgi scripts) that do not belong under the htdocs directory. To make sure that these files go in the right place, you need to use the -h switch to tell webapp-config the hostname of the website.

host must be a fully-qualified domain name.

If you do not use the -h switch, your virtual copy may not work correctly.

-D KEY=VALUE, --define KEY=VALUE

Define a configuration variable for webapp-config.

Allows to name a KEY=VALUE pair that will be imported into the configuration variables of webapp-config. This allows you to provide customized variables which can be used in the configuration file. This can also be used to temporarily overwrite variables from the configuration file.

-E variable name, --envvar variable name

Define an environment variable that will be picked up by webapp-config.

Allows to name single environment variable that will be imported by webapp-config. This allows you to provide customized variables which can be used in the configuration file. This can also be used to temporarily overwrite variables from the configuration file.

--envall

Imports all environment variables into the configuration process of webapp-config.

-V, --verbose

Use this option to increase the amount of output from the --list-installs switch.

-sf, --soft

Use this option to create the virtual copy using symbolic links.

You may find this option useful if /usr/share/webapps is on a different filesystem to your htdocs directories. However, it has been discovered that some packages do not work with this option, which is why it is no longer the default behaviour. You are always better off making /usr/share/webapps a symlink to a directory on the same filesystem as your htdocs directories.

-c, --copy

Use this option to create the virtual copy by copying the files from the /usr/share/webapps/ directories.

This option is useful if you want to copy the files directly from /usr/share/webapps/ to your virtual host in /var/www without the use of softlinks, or hardlinks. Be aware that because this is a direct copying of files it will prove to take up more space on your filesystem as opposed to the other two options since you are duplicating the webapp.

-S, --secure

Use this option to install into the htdocs-secure directory rather than into the htdocs directory.

This option is useful if you keep separate directories for your http: and https: sites.

You can change 'htdocs-secure' by editing the config file /etc/vhosts/webapp-config.

-dd type, --default-dirs type

type must be one of:

server-owned

Directories are owned by the user that the web server runs as. Use the -s switch to specify which web server to use.

config-owned

Directories are owned by the user and group specified with the -u and -g switches.

virtual

Directories are shared; no local copy is created.

-vf type, --virtual-files type

type must be one of:

server-owned

Files are owned by the user that the web server runs as. Use the -s switch to specify which web server to use.

config-owned

Files are owned by the user and group specified with the -u and -g switches.

virtual

Files are shared; no local copy is created.

EXAMPLES

All of these examples are aimed at Gentoo Linux. If you are using webapp-config on a different Linux distribution, they may not work out of the box for you.  

Installing applications

To install a copy of phpmyadmin-2.5.6, so that it is available from http://www.example.com/databases/admin/, you would do this:

webapp-config -I -h www.example.com -d /databases/admin/ phpmyadmin 2.5.6

To make sure that the shell account 'dbadmin' could edit the configuration files of phpmyadmin, you'd add the -u switch like this:

webapp-config -I -h www.example.com -d /databases/admin -u dbadmin phpmyadmin 2.5.6  

Upgrading applications

To upgrade the copy of phpmyadmin-2.5.6 to version 2.5.7, you would do this:

webapp-config -U -d /databases/admin/ phpmyadmin 2.5.7

To upgrade all the virtual copies of phpmyadmin-2.5.6, you would do this:

for x in `webapp-config --li phpmyadmin 2.5.6`;do . ${x}/.webapp && webapp-config -U -h ${WEB_HOSTNAME} -d ${WEB_INSTALLDIR} phpmyadmin 2.5.7; done  

Removing applications

To remove the copy of phpmyadmin-2.5.7, you would do this:

webapp-config -C -h www.example.com -d /databases/admin/

To remove all the virtual copies of phpmyadmin-2.5.7, you would do this:

for x in `webapp-config --li phpmyadmin 2.5.7`;do . ${x}/.webapp && webapp-config -C -h ${WEB_HOSTNAME} -d ${WEB_INSTALLDIR}; done  

FILES

/etc/vhosts/webapp-config

Configuration file, holding the defaults for webapp-config

/var/db/webapps

This directory tree holds information about the location of each virtual copy on the computer.

SEE ALSO

webapp.eclass(5), webapp-config(5), emerge(1)

webapp-config is based on the design for an installer for web-based application installers first defined in m[blue]GLEP #11m[][1] for the Gentoo Linux project.  

AUTHORS

Stuart Herbert <stuart@gentoo.org>, <stuart@gnqs.org>

Author.

Renat Lumpau <rl03@gentoo.org>

Author.

Gunnar Wrobel <php@gunnarwrobel.de>

Author.

Devan Franchini <twitch153@gentoo.org>

Author.

COPYRIGHT

NOTES

1.

GLEP #11

http://www.gentoo.org/proj/en/glep/glep-0011.html

Index

NAME

SYNOPSIS

DESCRIPTION

WEB-BASED APPLICATIONS AND VIRTUAL HOSTS

Two-Stage Install

Multiple Installations Of The Same Package

File Ownership And Permissions

Protected Configuration Files

File Copying Options

Virtual File Voodoo

${ROOT}

ACTIONS

OPTIONS

EXAMPLES

Installing applications

Upgrading applications

Removing applications

FILES

SEE ALSO

AUTHORS

COPYRIGHT

NOTES