[[PageOutline(2-5,Contents,pullout)]]

= Growl notification dispatcher for Trac events

== Description

This plugin dispatches change events that occur in a Trac project to Growl-enabled clients. [https://github.com/growl Growl] is a currently discontinued notification system for Mac OS X: it allows applications that support Growl to send you notifications on events in Trac, such as ticket changes and build changes. Growl itself is BSD-3 licensed.

This plugin uses remote notifications, using the local network. The server may run on any operating system, such as Linux, OS X, Windows or virtually any operating system that supports Trac.

The plugin does not rely on any third party libraries: no Growl SDK or library is required on the Trac server.

Currently supported event sources:
 * Ticket creation, deletion, and update.
 * Wiki page creation, deletion, and edition.
 * Attachment creation and deletion.
 * [http://bitten.edgewall.org Bitten] build startup, abortion and completion.

[[Image(growl-ticket.png)]]

== Bugs/Feature Requests

Existing bugs and feature requests for GrowlPlugin are 
[report:9?COMPONENT=GrowlPlugin here].

If you have any issues, create a 
[/newticket?component=GrowlPlugin new ticket].

[[TicketQuery(component=GrowlPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:growlplugin here].

== Source

You can check out GrowlPlugin from [/svn/growlplugin here] using Subversion, or [source:growlplugin browse the source] with Trac.

== Installation

For the prerequisites see the version requirement defined in [browser:growlplugin/0.11/setup.py setup.py] file, and search for ''install_requires''.

As with any other plugin:
{{{#!sh
python setup.py bdist_egg
}}}

Copy the generated egg file (from the `dist/` directory) to your project's plugins directory, or in the global plugin directory if you want to use it for more than one Trac project.

From the WebAdmin plugin interface or from your `trac.ini` file, enable the GrowlPlugin:
{{{#!ini
[components]
growl.notifier.* = enabled
}}}

== Configuration

The growl plugin can be configured with the help of the following settings in your `trac.ini` file:
{{{#!ini
[growl]
sources = wiki, ticket, attachment, bitten
hosts =
userprefs = false
}}}

Settings:
 * `sources` is a comma-separated list of source events:
   * `wiki` for wiki events
   * `ticket` for ticket events
   * `attachment` for attachment events
   * `bitten` for [http://bitten.edgewall.org Bitten] build events, only available if the Bitten plugin is installed and enabled
 * `hosts` is a comma-separated list of network hosts to send notification to
   * if `hosts` is not defined, then the notifications are broadcast onto the LAN, which could pose a security risk in some environments.
 * `userprefs` is a boolean option to allow per-user notification settings.

When enabled, any user who's been granted the `GROWL_MODIFY` permission may select which notifications (s)he wishes to receive, and the destination host which the notifications should be sent to.

=== Permissions

The plugin defines two new permissions:
 * `GROWL_MODIFY` permission allows a user to change the notification settings through the Growl plugin preference panel, and choose the destination host for the notifications.
 * `GROWL_ADMIN` gives the same privileges as `GROWL_MODIFY`, and allows the administrator to broadcast notifications to a sub network. To broadcast notifications, the administrator should use the special '<broadcast>` host.

=== Warnings

==== Notification overload

Note that there is no restriction on the number of plugin users, which might overload a Trac installation if too many hosts are set to receive various Growl notifications. This plugin is mainly oriented to small teams of users. Please also consider the use of the broadcast feature to reduce the number of notifications sent on every Trac event.

==== Security considerations

Your Trac-managed information may be at risk if you enable user preferences (see `userprefs` setting) and some random user chooses a host that is located outside your LAN. Only give `GROWL_MODIFY` permission to trusted users. 

Moreover, an untrusted user might set up his preferences to notify a foreign, remote host. Please ensure that Growl notifications are not routed
outside your own network (UDP:9887).

=== Preferences

When a user is granted the `GROWL_MODIFY` permission, the Growl plugin preference panel appears under the user preferences view:

[[Image(growl-userpref-panel.png, border=2)]]

A user which is granted the `GROWL_ADMIN` permission may select the `<broadcast>` special host address to broadcast notifications to all the hosts on the subnet.

=== Client configuration

==== Growl installation

Follow the Growl [http://growl.info/documentation/growl-package-install.php installation instructions].

==== Growl configuration

Growl should be configured to accept incoming notifications and remote application registration.
  1. Open Mac OS X system preferences.
  1. Select the Growl icon in the "''Other''" section.
  1. Select the "''Network''" pane.
  1. Enable the following check boxes:
     * ''Listen for incoming notifications''
     * ''Allow remote application registration''
  1. Leave the "''Server password''" field empty.

[[Image(growl-configuration.png)]]

'''Note:''' Growl server passwords are currently not supported.

== Recent Changes

[[ChangeLog(growlplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:eblot] [[BR]]
'''Maintainer:''' [[Maintainer]][[BR]]
'''Contributors:'''