

Rudimentary Installation Instructions for Double Choco Latte

Author: Michael L. Dean

$Id: INSTALL.lyx,v 1.1.1.1.2.3 2002/01/20 19:40:17 mdean
Exp $

1 Requirements

These items _must_ be setup, configured, and operating properly
for Double Choco Latte to function properly. We cannot provide
guidance for configuring this software. The accompanying
documentation for each package does a good job anyway.

1.1 Server Requirements 

1. Operating System which supports PHP/PostgreSQL/Apache

  * Linux

  * Windows NT, 2000 - should also work in 9x, Me as long
    as PHP works

  * I have gotten some e-mails in the past suggesting it
    works in *BSD and Solaris as well

2. Apache Web Server (http://www.apache.org/), IIS, or any
  web server supporting PHP

3. PHP (http://www.php.net/)

4. One of the following RDBMS

  (a) PostgreSQL (http://www.postgresql.org/)

  (b) MySQL (http://www.mysql.com/)

  (c) Micro$oft SQL Server

  (d) Sybase Adaptive Server Enterprise

1.2 Client Requirements 

JavaScript enabled browser. Sorry that this is a requirement,
but if you do not want something that is (fancy, evil) such
as JavaScript, you should probably look at some of the other
packages available for free such as: 

1. [http://mantisbt.sourceforge.net/||Mantis]

2. [http://fsck.com/rt/||Request Tracker]

3. [http://bugzilla.mozilla.org/||Bugzilla]

4. [http://samba.anu.edu.au/jitterbug/||Jitterbug]

2 Setup

Setup and upgrade scripts are now located under scripts/install
and scripts/upgrades respectively. Under there, go to the
SQL server used in your DCL installation for the proper
scripts. Upgrades are further segmented by database schema
version. Check the Version Info page for your current version
before upgrading!

2.1 Database

2.1.1 PostgreSQL

1. Create the database itself using the createdb command (i.e.,
  createdb dcl). dcl is the default name of the database.

2. Create the database schema by executing 'psql -e name_of_database
  < createdb.sql'

3. Grant access to the web server by editing the grant.sh
  file for your system and executing it (i.e., 'sh grant.sh').
  Be sure the grantTo variable is equal to the user the
  web server runs as (in httpd.conf for Apache).

2.1.2 MySQL

1. Create the database by executing 'mysqladmin [options]
  create dcl' and then 'mysql name_of_database < createdb.mysql'

2.2 Source Files

1. Put the DCL source files under the web server DocumentRoot.
  We used a subdirectory called 'dcl' for testing.

  (a) You don't have to move the entire tree over to the web
    server, and may not want to. Files and directories you
    should exclude are: INSTALL, README, TODO, ./inc/config.php.default,
    ./debian, ./docs, ./contrib, and ./scripts.

2. Copy config.php.default to config.php and edit config.php
  for your world. Comments are provided.

3. Access the system by using the URL you just created (i.e.,
  http://localhost/dcl/).

4. Login as sa with password sa. 

5. Change sa password through the Admin menu.

6. Go to system setup and follow the steps to set up the system.

3 E-Mail Gateway Installation

Starting with version 20011208, DCL includes an e-mail gateway
in the contrib/gateway directory of the distribution. The
gateway is a PERL script that expects to receive e-mail
piped to it from a MTA such as sendmail or postfix. This
section will attempt to provide some direction for installation
and configuration of the gateway, along with a basic overview
of how it works.

3.1 Operational Behavior

The steps involved in bringing tickets in through the e-mail
gateway can be summarized as follows. For the sake of providing
examples, we will assume Double Choco Latte (DCL) is the
product.

1. Issue reporter sends e-mail to dcl-support@mydomain.com

2. MTA for mydomain.com recognizes dcl-support as an alias
  and forwards it to the PERL script

3. PERL script sections the e-mail into headers, body, and
  attachments.

  (a) Defaults set from DCL config are: priority, severity,
    and status

  (b) From: is sectioned into name and e-mail address and inserted
    into contact and contact e-mail respectively

  (c) To: is sectioned to retrieve product name. The address
    is formatted as <product_abbreviation>-support@mydomain.com.
    The script retrieves the product abbreviation, looks
    it up in DCL, and sets the product ID for the ticket.
    If the product is not found, the script will exit with
    an error message.

  (d) The e-mail subject is inserted into the summary

  (e) The e-mail body is inserted into the issue field, minus
    any attachments

4. Using information in the headers, body, and DCL configuration,
  a ticket is constructed

5. The ticket is created and the files are "attached"
  to it

6. Optional e-mail response is sent to originator of e-mail

7. Responsible and watchers are notified of the new ticket

8. Optionally, responses to the ticket autoresponse e-mail
  are appended as ticket resolutions (TODO: this feature
  is not yet implemented)

3.2 Prerequisites

This has been used on a PERL installation as old as 5.005_03.
PERL modules required for this to operate include:

1. MIME::Base64

2. MIME::Parser

3. MIME::QuotedPrint

4. File::Basename

5. DBI

6. DBD driver for your SQL server (DBD::mysql or DBD::Pg)

7. Net::SMTP

You can install these packages from the CPAN shell (perl
-MCPAN -e shell) by doing install <packagename> (e.g., install
DBI)

3.3 Gateway Installation

1. Place the dcl-gateway.pl script in a suitable location
  (mine is in /etc/postfix). The postfix daemon must have
  read access to the directory and the file should have
  executable permissions.

2. Create a directory for the gateway script to use for temporary
  storage (I used /usr/local/dcl/tmp). The MTA daemon should
  have read, write, and execute for the directory. It also
  needs to be able to read, write, and exectute directories
  where the DCL attachments are stored (e.g., /usr/local/dcl).
  If this is not done correctly, any file attachments in
  the e-mail will not be attached to the ticket!

3.4 Configuration for Postfix MTA

1. Edit the /etc/aliases (or /etc/postfix/aliases) file.

  (a) Add aliases for each product you would like to route
    to the gateway.

  (b) Aliases should pipe to the gateway script

    i. dcl-support: "|/path/to/dcl-gateway.pl"

2. Run the newaliases command

3. Restart the postfix daemon (postfix reload)

3.5 Configuration for Sendmail MTA

1. Sendmail requires executable files be placed or linked
  in /etc/smrsh for security. Either ensure the dcl-gateway.pl
  file is in this directory or create a symbolic like from
  the file to the /etc/smrsh directory.

2. Edit the /etc/aliases file.

  (a) Add aliases for each product you would like to route
    to the gateway.

  (b) Aliases should pipe to the gateway script

    i. dcl-support: "|/path/to/dcl-gateway.pl"

3. Run the newaliases command

4. Restart the sendmail daemon (/etc/rc.d/init.d/sendmail
  restart)

3.6 Configure the Gateway Script

The only configuration that has to be done in the script
is setting up your database settings. This should match
how you have DCL set up. If you are using multiple domains
and want to receive e-mails for each domain, you will need
to create a copy of the gateway script for each domain.
Your aliases will point to the appropriate script depending
on the product in the To: address.

3.7 Configuring DCL for the Gateway

The Admin...System Setup...Configuration page now has a section
for configuring the e-mail gateway.

1. e-Mail Gateway for Tickets Enabled - must be checked in
  order for tickets to be created. Otherwise, an error will
  occur and the MTA will reject the e-mail.

2. Send Auto-Response to Sender Upon Receipt - If checked,
  a quick e-mail is sent to the originator of the e-mail
  informing them that the ticket was entered successfully
  into DCL.

3. Auto-Response e-Mail Address - The address to use in the
  From: field of the auto-response e-mail. Must be set to
  the same as your support address if the Allow Replies
  to Append Ticket Resolutions feature is to be used.

4. Allow Replies to Append Ticket Resolutions - if the ticket
  issuer responds to the auto-response e-mail, the resulting
  e-mail will be appended to the ticket as a ticket resolution.

5. Gateway Ticket Status - the status to assign tickets created
  by the gateway

6. Gateway Ticket Priority - the priority to assign tickets
  created by the gateway

7. Gateway Ticket Severity - the severity to assign tickets
  created by the gateway

8. Decode File Path for Ticket Attachments - the path to the
  temporary file area for decoding attachments.

Also, the e-Mail SMTP Server section is used to configure
the SMTP server used for outgoing e-mails. If the SMTP Enabled
option is deselected, the responsible person for the ticket
and the watchers will not receive e-mail notifications of
the ticket's entry. Regardless of the Enabled option, the
Server, Port, and Connection Timeout settings are still
used for auto-response e-mails.

4 FAQ

Q. I installed DCL on a Windows NT Server running IIS and
  PHP. When I try to login, I get a message saying "Could
  not verify session." What could be
  wrong?

A. More than likely, you are running PHP as a CGI handler.
  A known bug in IIS prevents cookies from being set properly
  if they are sent in the header along with a Location:
  header for redirection. The best fix at the moment is
  to change the redirMethod to meta.

Q. I went through the setup screen and configured DCL for
  our projects. Now when I try to enter a work order or
  ticket, the priorities and severities are empty after
  I select a product.

A. You need to add your new priorities and severities to
  the appropriate attribute sets. Go to Admin...System Setup...Attributes.
  Click on the View link for the set you want to modify.
  For each attribute, click on the Map link and use the
  forms to modify the available items and, in the case of
  priorities and severities, their weight (display order)
  in the drop downs.

Q. When trying to login to DCL, I get the login screen
  with a message that says "Could
  not verify session". I'm using IE.

A. Due to a strange bug in IE, you need to ensure you specify
  the trailing slash of the URL (i.e., http://host.com/dcl/
  and not http://host.com/dcl ). I assume this is a bug
  in IE since other browsers can cope with it just fine.

Q. After installing the files and setting up the database,
  I get this error when I go to index.php: Fatal error:
  Call to undefined function: setdbformat() in /path/to/datetime.php
  on line n.

A. The problem is caused by the Alternative PHP Cache (APC)
  being loaded. This error should no longer happen (since
  20010923 release). If you have the issue with a newer
  release, please report it.

If all else fails beyond repair, feel free to contact us. 

mdean at users.sourceforge.net
