
Please report your difficulties and provide other feedback here:

    mailto:john.bywater@appropriatesoftware.net


## Step-by-Step Install

### 1. Preliminaries

Basic Dependencies. Ensure you have available on your system:

    * Python >= 2.3
    * Apache >= 2.0
      * modpython (libapache2-mod-python on debian)
      * ssl [optional] (libapache2-mod-ssl on debian)
    * PostgreSQL (is recommended, but you can also use MySQL)

Python packages. The setuptools package is required by the Provide
installation, so it must be installed in advance. Other required modules:

    * psycopg (v1.1, not v2.0)
    * simplejson (v1.3 or higher)
    * sqlobject (v0.7 or higher, but not 0.8)
    * django v0.95 see http://www.djangoproject.com/download/
    * Python Imaging Library (debian package python-imaging)


System user accounts.

  1. Create a system user account called 'provide' (or something).
  2. Setup the environment (perhaps in /home/provide/.bashrc) so the
     umask is 0002.
  3. Add the Apache user to the 'provide' group (see Allowing For Dual Access).


### 2. Setup a relational database management system for Provide to use

You will need to have a database user with permission to create databases. We
suggest you use PostreSQL. Please consult the documentation of your database
management system for help.

  1. Create a new database user account called 'provide' with permission
     to create new databases. Set a password and remember what it is. If
     necessary, configure the database server to allow this user access
     to all databases (perhaps in relevent pg_hba.conf):
   
    $ createuser -P


### 3. Install the Provide system

Simply download and run the Provide installation script:

  1. Download the Provide installer:
    $ wget http://appropriatesoftware.net/provide/docs/provide-provide-0.4

  2. Run the Provide installer in bash:
    $ bash provide-provide-0.4 PATH DBUSER DBPASS DOMAIN SECRET

    PATH is an absolute path to an existing directory on your filesystem.
    DBUSER  Name of existing database user.
    DBPASS  Password of existing database user.
    DOMAIN  Name of domain that will be served by Provide.
    SECRET  Long random string, for security protocols.

  The Provide installer will check your system for the programs it needs.
  Please note that /bin/editor is often a symlink to either vi or emacs.

  The Provide installer will then create a directory called <PATH>/provided,
  if it doesn't exist. It will then create a subdirectory called '0.4'. If
  this second directory already exists the installer will terminate in error.

  Part way through installation, the new config file of your new Provide
  installation will be opened and presented for editing. Please check the
  values in this file carefully, and make sure to save any changes. Please
  also set whether the locations of your application services are to be
  distinguished by domain name, or path prefix. See config file for details.
  
  After the Provide installer has completed, please follow the instructions
  that are printed out. You will be asked to write some variables into your
  user's environment configuration.

  Please note you will need to hook up Apache configuration with the
  the 'purpose' Apache configuration files that are generated by the
  installed Provide scripts (eg provide-kforge-0.13). You can do this by
  using an Include directive, or with symlinks from 'sites-enabled'. The paths
  to these config files are normally printed out towards the end of the
  deployment of a provided application by Provide's 'designate' command. The
  'purpose' Apache config files are updated to include the Apache
  configuration of different application services when the service designated
  by the purpose changes, which means your will not need to update your Apache
  configuration when services are migrated for new releases.

  If you are distinguishing locations by path, you will need to Include the
  purpose config files within a virtual host directive. And to avoid confusing
  the execution of different service instances, you will need to have this
  mod_python directive set in your virtual host configuration:

  PythonInterpPerDirective On

  Example of virtual host config with path-distinguished Provide services:


NameVirtualHost *
<VirtualHost *>
    ServerName violet.appropriatesoftware.net
    PythonInterpPerDirective On
    Include /home/provide/provided/0.4/var/provisions/kforge/purposes/accept/etc/httpd.conf
    Include /home/provide/provided/0.4/var/provisions/kforge/purposes/testing/etc/httpd.conf
</VirtualHost>

   If you are running in 'path' mode, you will probably already have a virtual
   host and you will simply want to write the includes into existing config.

   Otherwise, if you are running in 'domain' mode, you will just want to
   symlink the purpose files into sites-available, and from there into
   site-enabled. In 'domain' mode, the purpose files are vhosts.



### 4. Final touches:

(There is further information on these items in the Extra Notes section below).

Set file permissions/ownerships (www-user is the user under which the web
server runs) on var directory (specified in config file):
  
  1. $ chown -R <www-user>:<www-user> PATH/provided/0.4/var

  2. Auto-reloading of web server configuration. Provide modifies Apache
     config when Provide purposes are redesignated to different services,
     and the Apache server must be restarted to picked up these changes.
  
     #[TODO]
     #1. EITHER set  to auto reload apache by unsetting the
     #   no_reload_apache config variable. Note that for this to work you will
     #   need to ensure appropriate permissions are granted to the user under
     #   which the Provide system runs (more details below).
     2. OR: automatically reload the apache configuration using some external
        means. For example, create a cron-job that automatically reloads apache
        configuration at regular intervals (example below) or a monitoring
        service of some kind (such as monit) to reload apache each time the
        Apache config file is rebuilt (example below).


### 5. Restart/reload the webserver

    $ sude apache2ctl restart


### 6. That's it, you are done!

You could try installing KForge (provide-kforge-X) or ScanBooker... Or you
could try to write a Provide plugin for your favorite application.


### 7. Removing Provide.

You will want firstly to remove any created provisions. You can list and
remove the provisions that have been created with this example command:

    $ provide provisionlist
    kforge
    trac

    $ provide remove kforge
    $ provide remove trac

Then you can drop the Provide database:

    $ provide db delete

Then you can remove the Provide filesystem:

    $ rm -rf PATH/provided/0.4

Where PATH is the path that was given to the installer (see above).


## Additional Notes

Setting File Permissions
========================

For web access to work for Provide you must allow the web server (Apache)
access to Provide files. To do this you have two options:

  1. Have web user own all Provide files.  This may cause problems if you
     then wish to run command line utilities to administer Provide, since
     you may not have permission to write to files and directories owned
     by the web-user.

  2. Allow for dual access by the Provide user and the web-user.

Allowing for Dual Access
------------------------

A suitable umask value UMASK to allow group access is 002 or 007.

  1. Set umask for <provide-user> so that group also has 
     write permissions. Add the following line to the your
     environment setup (e.g. ~/.bashrc):
    $ umask UMASK
  
  2. Give web user access to the Provide installation by
     adding <apache-user> to <provide-user> group:
    $ usermod -G<provide-user-group> <apache-user>
  
  3. Set umask for Apache to allow group access. Add the following
     to Apache startup script (usually /usr/sbin/apache2ctl or
     /usr/sbin/apache2ctl -- you can find it referenced in
     /etc/init.d/apache<version>):
    umask UMASK
      
  4. Give group access to existing files and make sure new files and
  directories remain in the <provide-user-group> by setting sgid:
    $ chmod g+wX -R  

Allowing for Auto-Reloading of the Apache Configuration
=======================================================

It is occasionally necessary for the Provide system to update the Apache
configuration file (for example when new services are added). For these
changes to take effect it is then necessary for Apache to reload the
configuration. There are two options for how this is done:

Automatically
-------------

In the [www] section of the Provide configuration file set the no_reload_apache
to empty (False) and set the reload_apache variable to the command which will
reload the Apache configuration on your system.

NB: In order for this to work the user which owns the Apache process must be
able to reload the configuration.  Specifically it must be able to run the
'reload_apache' command specified in the [www] section of the configuration.
You can normally achieve this by adding something to your /etc/sudoers file:

  > Cmnd_Alias APACHE = <insert-apache-reload-command>
  > [....]
  > <www-user-name> ALL =NOPASSWD: APACHE

Manually
--------

Reload the Apache config on a regular basis using some external tool. For
example the following uses cron to reload Apache config every half an hour:

# Reload Apache config every half an hour.
# The Apache reload command is for Apache v2 on Debian
# and might need to be modified for other systems.
30 * * * *   /etc/init.d/apache2 reload

Alternatively you could use some form of monitoring service to only reload when
Provide rebuilds its Apache configuration file. For example, the following uses
monit:

check file monit_flag_tmp with path ${path-to-provide-generated-apache-config}
  # replace time with check period of your monit process
  if timestamp < 10 minutes then reload_apache

