next_inactive up previous


Rudimentary Installation Instructions for Double Choco Latte

Author: Michael L. Dean

$Id: INSTALL.html,v 1.1.1.1.2.3 2002/01/20 19:40:53 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

  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

    1. PostgreSQL (http://www.postgresql.org/)
    2. MySQL (http://www.mysql.com/)
    3. Micro$oft SQL Server
    4. 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. Mantis http://mantisbt.sourceforge.net/
  2. Request Tracker http://fsck.com/rt/
  3. Bugzilla http://bugzilla.mozilla.org/
  4. Jitterbug http://samba.anu.edu.au/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.

    1. 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.

    1. Defaults set from DCL config are: priority, severity, and status
    2. From: is sectioned into name and e-mail address and inserted into contact and contact e-mail respectively
    3. 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.
    4. The e-mail subject is inserted into the summary
    5. 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.

    1. Add aliases for each product you would like to route to the gateway.
    2. Aliases should pipe to the gateway script

      1. 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.

    1. Add aliases for each product you would like to route to the gateway.
    2. Aliases should pipe to the gateway script

      1. 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

About this document ...

Rudimentary Installation Instructions for Double Choco Latte

This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.50)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir12956nTtkJq/lyx_tmpbuf12956qLevFP/INSTALL.tex

The translation was initiated by Mikey on 2002-01-20


next_inactive up previous
Mikey 2002-01-20