/
INSTALL
250 lines (178 loc) · 10.3 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
=====================
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-id=1
For Postfix::
bugs: |"/usr/bin/whups-mail-filter --queue-id=1"
This will take in mail to the ``bugs`` address at your domain, and create
new tickets in the queue 1, 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