******************************************************************************
*
*                                 APPIE!
*
******************************************************************************

Contents
--------
0. Introduction
1. General application setup
2. Appie Modules
3. Usage


0. Introduction
---------------

Appie is the application maintenance tool for GW20E. Appie is a
framework for modules that can perform specific tasks, like setting up
and application environment, setting up a Plone instance, etc. Some
module/command pairs require root permissions, like configuring
Apache, but most tasks can be performed by common users, as long as
they are member of the appadmin group.


1. General application setup
----------------------------

Appie is based upon the notion of an application specific directory
structure, where an application and its (specific) software resides
in its own directory, and holds its own environment variables. The
application has its own user.

The structure for these application users is based upon idea that an
application may need a maximum of three different environments,
namely TST for testing, ACC for end user testing and PRD for
production. An environment may be distributed over two machines, when
clustered. Applications have a specific type, like for instance
'zope', 'plone', etc. The type can be used to provide grouped shares
for a type of application, for example shared sources.

The application environment will be structured as follows:

$APP_BASE/<application>/<environment>.

Per application/environment pair, a user is created with the id
app-<application>-<environment>. 

Let's take an example. We have application appX.  We need an environment for
TST and PRD. We'll end up having:

Users:
	appX-tst
	appX-prd

Groups:
	appX: appX-tst, appX-prd

Directories:
	$APP_BASE/appX/tst
	             ./prd


All people in the group appadmin can switch to all environment (tst,
acc, ...) specific users.  This can be achieved with the 'appie
become' command, and the sudoers config file.

For all users that need to be able to manage an application, or just
one environment for an appliction add the visudo command):

<user id>  ALL = NOPASSWD: /bin/su <app id>-<env id>

You may use * instead of env id, to enable su to any environment.
All users need to be able to login on a machine as themselves.

Administrative users for Appie should be in the group appadmin, and
this group should have write permissions on the APP_BASE.

2. Appie Modules
----------------

A module for Appie is very simple: you'll need to add a directory to
the modules dir, provide a number of shell scripts in that directory,
with the default script named 'main'. Also, please provide the
necessary reading material.

A description of the module that can be displayed by appie, should be
available in a file called DESCR.

Any script should at least give some info when called with help as
argument, and bail out.

Modules preferrably should be able to do all necessary functionality
based on command line parameters, and may provide interactive use on
top of that.

To use another module from your own module, use $APPIE <module>. APPIE
 holds the global command for the appie interpreter.

For module specific info, check the README within that module
directory, if there is one...


2.1 Application ports
---------------------

Some applications need one or more ports. Appie can assign one or more
ports to an application, and will set the following environment
setting, based on a port base, defined in appie.conf.

APP_PORT_BASE
APP_PORT_LAST

The first will contain the base port for this application, the second
will show the last of allocated ports.


3. Configuration
----------------

Appie configuration files are:

appie.conf	Main config file. Copy appie.conf.example to appie.conf
		and adjust settings to your personal needs.
hosts		List of appie enabled hosts

Apart from that, every module may hold extra configuration in a file
called <module id>.conf, within its own directory. All configuration
will be available as global environment variables.


4. Usage
--------

Use Appie as follows:

	appie help | (<module[:command]> [module options])

For example to start a new application environment, type:

	appie app

or (equivalent):

	appie app:main


3. Exit codes
-------------

An exit code of 0 is considered to be good, anything else isn't...
Use codes like so:

0 user intervention or regular stop
1  Parameter problems
50 Permission problems


4. Prerequisites
----------------

Applications should conform to some rules, for appie to be able to
work. Applications normally should be self contained, that means: all
necessary stuff should be in the application directory. If this is not
the case, extra directories to be used should be listed in the profile
variable ADDITIONAL_LOCATIONS.