======================
 Installing Whups 1.0
======================

:Last update:   $Date: 2008/08/28 09:39:33 $
:Revision:      $Revision: 1.25 $
:Contact:       dev@lists.horde.org

.. contents:: Contents
.. section-numbering::

This document contains instructions for installing the Whups web-based
ticket-tracking application on your system.

For information on the capabilities and features of Whups, see the file
README_ in the top-level directory of the Whups distribution.


Obtaining Whups
===============

Whups can be obtained from the Horde website and FTP server, at

   http://www.horde.org/whups/

   ftp://ftp.horde.org/pub/whups/

Or use the mirror closest to you:

   http://www.horde.org/mirrors.php

Bleeding-edge development versions of Whups are available via CVS; see the
file `horde/docs/HACKING`_ in the Horde distribution, or the website
http://www.horde.org/source/, for information on accessing the Horde CVS
repository.


Prerequisites
=============

To function properly, Whups **requires** the following:

1. A working Horde installation.

   Whups runs within the `Horde Application Framework`_, a set of common
   tools for Web applications written in PHP.  You must install Horde before
   installing Whups.

   .. Important:: Whups 1.0 requires version 3.2+ of the Horde Framework -
                  earlier versions of Horde will **not** work.

   .. _`Horde Application Framework`: http://www.horde.org/horde/

   The Horde Framework can be obtained from the Horde website and FTP server,
   at

      http://www.horde.org/horde/

      ftp://ftp.horde.org/pub/horde/

   Many of Whups's prerequisites are also Horde prerequisites.

   .. Important:: Be sure to have completed all of the steps in the
                  `horde/docs/INSTALL`_ file for the Horde Framework before
                  installing Whups.

2. The following PHP capabilities:

   a. SQL support

      Whups stores its data in an SQL database. Build PHP with whichever SQL
      driver you require; see the`horde/docs/INSTALL`_ file for details.


Installing Whups
================

Whups is written in PHP, and must be installed in a web-accessible directory.
The precise location of this directory will differ from system to system.
Conventionally, Whups is installed directly underneath Horde in the web
server's document tree.

Since Whups is written in PHP, there is no compilation necessary; simply
expand the distribution where you want it to reside and rename the root
directory of the distribution to whatever you wish to appear in the URL. For
example, with the Apache web server's default document root of
``/usr/local/apache/htdocs``, you would type::

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/whups-h3-x.y.z.tar.gz
   mv whups-h3-x.y.z whups

and would then find Whups at the URL::

   http://your-server/horde/whups/


Configuring Whups
=================

1. Configuring Horde for Whups

   a. Register the application

      In ``horde/config/registry.php``, find the ``applications['whups']``
      stanza. The default settings here should be okay, but you can change
      them if desired. If you have changed the location of Whups relative to
      Horde, either in the URL, in the filesystem or both, you must update the
      ``fileroot`` and ``webroot`` settings to their correct values.

2. Creating the database table

   The specific steps to create the Whups database table depend on which
   database you've chosen to use.

   First, look in ``scripts/drivers/`` to see if a script already exists for
   your database type. If so, you should be able to simply execute that script
   as superuser in your database.

   If such a script does not exist, you'll need to build your own, using the
   file ``whups.sql`` as a starting point. If you need assistance in creating
   databases, you may wish to let us know on the Whups mailing list.

3. Configuring Whups

   To configure Whups, change to the ``config/`` directory of the installed
   distribution, and make copies of all of the configuration ``dist`` files
   without the ``dist`` suffix::

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Or on Windows::

      copy *.dist *.

   Documentation on the format and purpose of those files can be found in each
   file. You may edit these files if you wish to customize Whups's appearance
   and behavior. With one exception (``reminders.php``, in case you want to
   automatically sent out reminders about open tickets) the defaults will be
   correct for most sites.

   The ``create_email.txt`` and ``notify_email.txt`` files define how outgoing
   email notifications about new respectively updated tickets look like. If
   using non-ascii character in this file, it has to saved with UTF-8
   encoding. The following placeholders are available:

      :@@ticket_url@@: The link to the ticket page.
      :@@table@@:      The ticket summary table.
      :@@comment@@:    The last user comment if any, including leading
                       linebreaks.
      :@@dont_reply@@: The message telling users to not reply, if enabled in
                       the configuration, including trailing line breaks.
      :@@date@@:       The current date.
      :@@full_name@@:  The full name of the notification recipient.
      :@@auth_name@@:  The full name of the user that updated the ticket.

   You can also specify queue-specific notification messages by creating
   seperate files with the following naming convention: ``create_email_X.txt``
   will be used for ticket creation emails for queue "X";
   ``notify_email_Y.txt`` will be used for notification emails for queue "Y".

   You must login to Horde as a Horde Administrator to finish the
   configuration of Whups. Use the Horde ``Administration`` menu item to get
   to the administration page, and then click on the ``Configuration`` icon to
   get the configuration page. Select ``Tickets`` from the selection list of
   applications. Fill in or change any configuration values as needed. When
   done click on ``Generate Tickets Configuration`` to generate the
   ``conf.php`` file. If your web server doesn't have write permissions to the
   Whups configuration directory or file, it will not be able to write the
   file. In this case, go back to ``Configuration`` and choose one of the
   other methods to create the configuration file ``whups/config/conf.php``.

   If you would like the ability to create and update tickets via
   email, you will need to set up ``whups/scripts/mail-filter.php`` to
   receive email from the appropriate addresses. This script takes a
   number of arguments; see the script for more details. A typical
   setup might be::

      bugs |/path/to/horde/whups/scripts/mail-filter.php --queue-name=Bugs --type-name=Bug --state-name=New --priority-name=Low

   This will take in mail to the ``bugs`` address at your domain, and
   create new tickets in the ``Bugs`` queue, with a type of ``Bug``, a
   state of ``New``, and ``Low`` priority. Note that this must be a
   valid combination of queue/type/state/priority names in your Whups
   installation. If an email references an existing ticket (ticket
   numbers are recognized in the subject line) it will be updated
   instead.

   Note for international users: Whups uses GNU gettext to provide local
   translations of text displayed by applications; the translations are found
   in the ``po/`` directory. If a translation is not yet available for your
   locale (and you wish to create one), see the ``horde/po/README`` file, or
   if you're having trouble using a provided translation, please see the
   `horde/docs/TRANSLATIONS`_ file for instructions.

4. Testing Whups

   Use Whups to create your base data, create tickets, and modify
   tickets. Test at least the following:

     - Creating a new project (queue)
     - Creating ticket types, states, priorities for a project
     - Adding a ticket
     - Assigning a ticket
     - Closing a ticket

5. Creating tickets from email messages

   Whups provides functionality that can be used to create and update tickets
   from email messages. One part of this functionality is the
   ``mail-filter.php`` in the ``whups/scripts/`` directory. It can either be
   installed inside the mail chain, or run as a standalone script against an
   IMAP or POP3 server. It provides a list of all available command line
   arguments if called with the ``--help`` argument: ``./mail-filter.php
   --help``.

   If you use the arguments starting with ``--mail``, the script will login to
   the provided IMAP or POP3 server and process all messages in the specified
   folder. Any successfully processed messages will be deleted. An error
   message will be displayed for any failed messages. Using the script in this
   mode makes most sense when run regularly, e.g. by a cron job or the Windows
   task planner.

   You can also install the script inside the mail chain. In this mode, the
   script expects a single email message from standard input. A common
   scenario would be to pipe all messages to a certain email address through
   this script, e.g. through the forwarding or alias mechanism. An example
   entry in ``/etc/alias`` could look like this::

      bugs:"|/pathtohorde/whups/scripts/mail-filter.php -q 'Test Queue' -t mytype -p '1. Low' -s Unconfirmed"

   Even though this example uses "names" for the arguments, it's preferred to
   use IDs, because those doesn't cause any problems with spaces, or non-ascii
   characters.

   The script tries to determine the ticket number from the message, if a
   ticket number hasn't been specified with the ``--ticket``
   argument. Currently it searches for strings looking like "[Bug #1]" in the
   message subject. If a ticket number cannot be determined by any means, or
   if a ticket with that number doesn't exist, a new ticket is created.

   The (Horde) user that will be used to create or update the ticket, will
   also be determined by investigating the message. The email address used in
   the ``From:`` header of the message will be looked up by searching all
   identities of all users in the authentication backend. This only works if
   the authentication backend is capable of listing users. If a user cannot be
   determined this way, the user provided by the ``--default--auth`` argument,
   if any, is used. Finally, if none has been provided, the user specified in
   Whups' configuration (``$conf[mail][username]``) will be used. If there
   still hasn't been a user determined at this point, the ticket will be
   updated or created by the "guest" user, using the email address of the
   ``From:`` header. This only works if guest access has been granted to both
   Whups, and the queue specified with the ``--queue-name`` or ``--queue-id``
   parameters.

   Finally, you might want to to enable the setting in Whups' configuration,
   below the "Email Settings" tab, that allows users to reply to ticket
   emails. This setting removes the warning from the generated ticket emails
   to *not* reply to those emails. And you should of course make sure that you
   specify the correct email address here for the generated messages. It
   should the address that you use for the mail pipe, or the IMAP/POP3 account
   when calling ``mail-filter.php``.


Obtaining Support
=================

If you encounter problems with Whups, help is available!

The Horde Frequently Asked Questions List (FAQ), available on the Web at

  http://www.horde.org/faq/

The Horde Project runs a number of mailing lists, for individual applications
and for issues relating to the project as a whole. Information, archives, and
subscription information can be found at

  http://www.horde.org/mail/

Lastly, Horde developers, contributors and users may also be found on IRC,
on the channel #horde on the Freenode Network (irc.freenode.net).

Please keep in mind that Whups is free software written by volunteers.
For information on reasonable support expectations, please read

  http://www.horde.org/support.php

Thanks for using Whups!

The Whups team


.. _README: ?f=README.html
.. _`horde/docs/HACKING`: ../../horde/docs/?f=HACKING.html
.. _`horde/docs/INSTALL`: ../../horde/docs/?f=INSTALL.html
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/?f=TRANSLATIONS.html
