next_inactive up previous


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

  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

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.

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

    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.

dcl-support@gnuenterprise.org

About this document ...

Rudimentary Installation Instructions for Double Choco Latte

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.70)

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_tmpdir978DABOF0/lyx_tmpbuf0/INSTALL.tex

The translation was initiated by Michael on 2003-11-04


next_inactive up previous
Michael 2003-11-04