======================
 Installing Whups 2.0
======================

: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.


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 2.0 requires version 4.0+ of the Horde Framework -
                  earlier versions of Horde will **not** work.

   .. Important:: Be sure to have completed all of the steps in the
                  `horde/docs/INSTALL`_ file for the Horde Framework before
                  installing Whups. Many of Whups's prerequisites are also
                  Horde prerequisites. Additionally, many of Whups's optional
                  features are configured via the Horde install.

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

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
================

There are several ways to install Whups. The recommended way to install Whups
is using the PEAR installer. Alternatively it can be installed from
tarballs. Finally, if you want to run the latest development code, or get the
latest, not yet released, fixes, you can install Whups from Git.


Installing with PEAR
~~~~~~~~~~~~~~~~~~~~

First follow the instructions in `horde/docs/INSTALL`_ to prepare a PEAR
environment for Horde and install the Horde Framework.

When installing Whups through PEAR now, the installer will automatically
install any dependencies of Whups too. If you want to install Whups with all
optional dependencies, but without the binary PECL packages that need to be
compiled, specify both the ``-a`` and the ``-B`` flag::

   pear install -a -B horde/whups-beta

By default, only the required dependencies will be installed::

   pear install horde/whups-beta

If you want to install Whups even with all binary dependencies, you need to
remove the ``-B`` flag. Please note that this might also try to install PHP
extensions through PECL that might need further configuration or activation in
your PHP configuration::

   pear install -a horde/whups-beta


Installing from Release Tarballs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. Important:: As of today, there are no tarballs released for Whups 2
               yet. Please use the `Installing with PEAR`_ method to install
               Whups 2.

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

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

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

Or use the mirror closest to you:

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

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 Whups

   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``.

   Documentation on the format and purpose of the other configuration files and
   templates in the ``config/`` directory can be found in each file. You may
   create ``*.local.php`` versions of these files if you wish to customize
   Whups' appearance and behavior. See the header of the configuration files
   for details and examples. 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 ``*_email.plain.php`` files define how outgoing email notifications
   about ticket changes look like. See the comments in these files for details.

   If you would like the ability to create and update tickets via email, you
   will need to set up ``whups-mail-filter`` 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 |/usr/bin/whups-mail-filter --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.

   If not installing Whups through PEAR of if PEAR's ``bin_dir`` configuration
   doesn't point to ``/usr/bin/``, replace ``/usr/bin/whups-mail-filter`` with
   the path to the ``whups-mail-filter`` script in your Horde installation.

   See also `Creating tickets from email messages`_ below.

2. Creating the database table

   Once you finished the configuration in the previous step, you can create all
   database tables by clicking the ``DB schema is out of date.`` link in the
   Whups row of the configuration screen.

   Alternatively creating the Whups database tables can be accomplished with
   horde's ``horde-db-migrate`` utility.  If your database is properly setup in
   the Horde configuration, just run the following::

      horde-db-migrate whups

3. 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

4. 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
   ``whups-mail-filter`` script. 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:"|/usr/bin/whups-mail-filter -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
   be the address that you use for the mail pipe, or the IMAP/POP3 account when
   calling ``whups-mail-filter``.


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

If you encounter problems with Whups, help is available!

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

  http://wiki.horde.org/FAQ

Horde LLC 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/community/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/community/support

Thanks for using Whups!

The Whups team


.. _README: README
.. _`horde/docs/INSTALL`: ../../horde/docs/INSTALL
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/TRANSLATIONS
