Rudimentary Installation Instructions for Double Choco Latte

Author: Michael L. Dean

$Id: INSTALL.lyx,v 1.1.1.1.2.3.2.2 2003/03/04 03:33:20 
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

Starting with version 0.9.4, DCL has a web-based 
install/upgrade interface. It was derived from the code 
used for XOOPS setup. Be sure to backup your database 
prior to running the upgrade! It is much better to be 
safe than sorry in this respect.

Point your browser to 
http://where.did.I.install/dcl/setup to begin the 
wizard. It will ask you for your database connection 
information. If you use a database user that is capable 
of creating databases and this is a new installation 
with no database, the setup wizard will attempt to 
create the database for you. If the user you will be 
connecting as through DCL does not have this privilege, 
you will need to manually create your database. See 
your documentation for your SQL server to learn how to 
do this if necessary.

After you are finished with the setup wizard and have 
verified this install is working properly, delete the 
setup directory!!! It is an obvious security risk to 
leave this directory intact. Another option is to 
protect the setup directory with web server security 
(such as .htaccess and .htpasswd files for Apache). 
Removing the setup directory is highly recommended, however.

2.1 Source Files

1. Put the DCL source files under the web server 
  DocumentRoot. We used a subdirectory called 'dcl' for 
  testing. You may also create a virtual directory for 
  DCL. See the documentation for your web server for 
  instructions on how to accomplish this.

  (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. Install the system (http://localhost/dcl/setup/) as 
  documented above. If upgrading, backup your database 
  before running setup!

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...Change 
  Password menu option.

6. Go to Admin...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. 

dcl-support@gnuenterprise.org
