Instructions for installing MiniReq
===================================

Overview:
 1. Basic Explanation
 2. Pre-Configure
 3. Decisions - the defs file.
 4. Install it to test it.
 5. Install it for real.
 6. Install any interfaces.
 7. Learn how to use it.
 8. Get on the update mailing list if you care.


1. Explanation
--------------
Read the file docs/blurb.  It explains at a relatively high level how
the system works - enough so that you can make decisions about how to
install it.


2. Configure
----------------

  MinReq uses GNU autconf to figure out a lot of things.  There are many
parameters which are necessarily very site specific.  The configure script
will attempt to provide defaults for every setting, but that does not mean
that it is always a good idea to use the provided defaults.  The configure
script outputs a file called 'defs', which is used by the 'extract' script
(also generated by configure) to substitute into nearly every other file
in the package.

To generate the 'defs' file, (amongst other things), run:

   ./configure <args>

the arguments are standard configure arguments (like --prefix), and
arguments specific to MiniReq.  To see a list of all known arguments,
run:

   ./configure --help

Watch the output.  It should show either the defaults that it is
selecting for various things, or the values you provided on the
command line.  When it's done, you should edit the 'defs' file to
change those things which are specific to your site.


3. Decisions
------------
There are quite a few configuration options that you can set by editing
the values in the "defs" file, and that's what you should do now.

Pay particular attention to the mail addresses, any full (user@foobar.org)
addresses must be escaped (user\@foobar.org) and the user/group settings
as these determine file permissions.     

If you would like to see what the paths in your defs file will look
like when fully expanded, run:
  ./extract defs > /tmp/defs.out
And then read '/tmp/defs.out'.  You don't have to do this, but it might
help make more sense out of the insanity towards the end of the defs
file.


4. Test it
----------
Having now edited the defs file, you should install a test case to see
how it works.  (You don't want mail sent to your list to die if there's
some problem.)

  A.  Pick a test alias.   'test' may be good, if it's not being used.

  B.  Update the 'defs' file to use 'test' as the alias name, and
      'test-dist' as the recipient's alias.

  C.  Create the login that it will run as.
       - Make sure the password is unusable.  "*" works well.
       - The shell probably should be usable so that the cronjob will
         work.

  D.  Create the group that you mentioned as REQUEST_GROUP, and put
      anyone in it who should have access to the request system.  
      (Probably the same people as are on the list.)

  E.  Put a mail alias in for the test alias, and an alias in for the 
      distribution:

            test:           |"/path/to/req/etc/req-mailgate"
            test-dist:      firstuser, seconduser, etc

      You may need to run 'newaliases' or something else... this is
      system dependent.  Make sure you put in the real path to your
      mailgate.
      
  F.  In the top of the distribution directory (the directory containing
      the "defs" file):

         make

      This should build all the programs.

  G.  As root, or as the user you picked for the request system:

         make install

      This requires privileges because it makes some programs setuid.

  H.  Initialize the queue:

      SKIP THIS STEP if you've already installed MiniReq before to this
      location.

      Still as root or the MiniReq user:

         make init

      This sets up a few config files (right now only the current users
      file and the nextnum file) which may or will change when the queue
      is in use.

You're done with the install.  If some part doesn't work out because of
strange permissions or such, do a 'make -n <target>' to see what would
have happened, and then do it by hand.  This may be necessary under
certain shared directory conditions.  Sigh.

Now test it.  Send mail to 'test'.  If it bounces, there's a problem.
Run 'q'.  It should show a request (probably number 1) in the queue.
Run 'req -show 1'.  You should see the message.  At this point, play
around with the system.  Read the manual pages.


5. Install it for real
----------------------

   A. Edit the 'defs' file so that it says the name of the real 
      mailing list that you want to filter into the request system.

   B. Update the aliases file to have the real aliases.
       
   C. make clean

   D. Follow all the instructions in number 3, starting at F.  (make all)


6. Drop in the cron job
-----------------------
Arrange with cron to run the "req-daily" script that should be in the 
etc/ directory of the install tree.  The req-daily script runs 
glimpseindex on the active and resolved queues to allow easy indexing.

This should be run as the user who owns the request system.  You could 
put in a crontab entry for this user, or from root's crontab or daily 
script, you could do:

    su ${REQUEST_USER} -c req-daily

(Substitute the appropriate user name and path name.)

This should be done on the machine where the requests will be stored.


8. Customize
------------
The autoreply message should definitely be customized to your site.  We've
provided one in that was probably installed as req-autoreply, but the
messages (hours, and so on) will probably not be appropriate to your
installation.

You should modify that program (or write your own) to do as you see fit.

9. You're done
--------------
Things you might want to read:
   docs/changes   - Changes made in recent releases
   docs/intro     - An intro to using it.
   docs/use       - Suggestions on how to use the request system.
   docs/wish.list - The current list of requested features and comments
                    about them.
   The manual pages also contain quite a lot of detail.
