rt/docs/extensions.pod

   1 =head1 Introduction
   2
   3 RT has a lot of core features, but sometimes you have a problem to solve
   4 that's beyond the scope of just configuration. The standard way to add
   5 features to RT is with an extension, or plugin -- RT uses the terms
   6 interchangably.
   7
   8 =head1 Finding extensions
   9
  10 Most of the extensions written by Best Practical (and quite a few
  11 contributed by the community) are available from CPAN; a L<search for
  12 RT::Extension|https://metacpan.org/search?q=RT::Extension::> will turn
  13 up most of them.  The Best Practical website also maintains a list, at
  14 L<http://www.bestpractical.com/rt/extensions.html>
  15
  16 =head1 Installing extensions
  17
  18 RT extensions should be installed by downloading the C<.tar.gz> file for
  19 the extensions, extracting it (with C<tar xzf filename.tar.gz>), and
  20 following the instructions in its included F<README>.
  21
  22 The instructions under C<INSTALLING> in the F<README> always take
  23 precedence over those found here.  In general, however, the process is
  24 as follows:
  25
  26 =over
  27
  28 =item 1.
  29
  30 B<Run C<perl Makefile.PL>> to check for dependencies, and minimum
  31 versions of RT.  If your RT is in an unusual location (not
  32 C</opt/rt4/>), you may need to set the C<RTHOME> environment variable to
  33 the root of your RT location.
  34
  35 =item 2.
  36
  37 B<Run C<make>> to prepare the package for installation.
  38
  39 =item 3.
  40
  41 B<Run C<make install>>; you may need to run this step as C<root>, or at
  42 least a user that has permission to install into RT's directories.
  43
  44 =item 4.
  45
  46 If the extension contains database changes or new queues, scrips,
  47 templates, or the like, you will need to B<run C<make initdb>> to install
  48 them.  Not all extensions have database changes, and most of them only
  49 need this step run when they are first installed, and not on later
  50 updates.  Refer to the C<INSTALLING> section of the module's
  51 documentation.
  52
  53 =item 5.
  54
  55 B<Add the plugin to RT's configuration.> By default, newly installed
  56 plugins are not enabled.  On RT 4.2, each plugin should be enabled by
  57 the C<Plugin()> command:
  58
  59     Plugin( 'RT::Extension::Example' );
  60     Plugin( 'RT::Extension::Sample' );
  61
  62
  63 On RT 4.0, enabling them instead requires adding them to the C<@Plugins>
  64 configuration:
  65
  66     Set( @Plugins, 'RT::Extension::Example', 'RT::Extension::Sample' );
  67
  68 =item 6.
  69
  70 B<Configure any additional settings> that the extension requires.  Many
  71 options that must be set before the plugin can be used.  Read the
  72 documentation carefully.
  73
  74 =item 7.
  75
  76 Next, B<clear the cache>.  RT caches the files it serves, and installing
  77 a plugin requires clearing this cache to ensure that the changes are
  78 served.  This is done by removing files in the
  79 F</opt/rt4/var/mason_data/obj> directory:
  80
  81    rm -rf /opt/rt4/var/mason_data/obj
  82
  83 This step may not be necessary if the extension does not affect RT's
  84 display.
  85
  86 =item 8.
  87
  88 Finally, B<restart your webserver>.  The steps for this will vary from
  89 webserver to webserver.
  90
  91 =back
  92
  93 Again, the above are generalizations.  The C<README> shipped with the
  94 extension always takes precedence over the above steps.
  95
  96
  97 We do not suggest using the command-line C<cpan> or C<cpanm> client to
  98 install RT extensions, despite them being available from CPAN.  Those
  99 command-line clients are not aware of steps 4-8 listed above, and may
 100 result in an incomplete installation.
 101
 102 =cut