=====================
 Installing Whups H5
=====================

: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 H5 requires version 5.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
================

The **RECOMMENDED** way to install Whups is using the PEAR installer.
Alternatively, 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

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

   pear install horde/whups

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

Installing from Git
~~~~~~~~~~~~~~~~~~~

See http://www.horde.org/source/git.php


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

   This will take in mail to the ``bugs`` address at your domain, and create
   new tickets in the ``Bugs`` queue, with the default type, state and priority
   of this queue. 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: ``whups-mail-filter --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'"

   Even though this example uses a queue "name" for the argument, 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``.

   Any attachments that have been sent with the message will be added to the
   ticket as attachments too. This is done via the virtual file system (VFS) of
   Horde. If you use the local file system as the VFS backend, you need to take
   care of permissions and umasks, i.e. both the user running the
   ``whups-mail-filter`` script and the user running the web server need to
   have read-write permissions to the VFS storage directory.


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

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