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 $
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.
- 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
- Apache Web Server (http://www.apache.org/), IIS, or any web server
supporting PHP
- PHP (http://www.php.net/)
- One of the following RDBMS
- PostgreSQL (http://www.postgresql.org/)
- MySQL (http://www.mysql.com/)
- Micro$oft SQL Server
- Sybase Adaptive Server Enterprise
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:
- Mantis http://mantisbt.sourceforge.net/
- Request Tracker http://fsck.com/rt/
- Bugzilla http://bugzilla.mozilla.org/
- Jitterbug http://samba.anu.edu.au/jitterbug/
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!
- Create the database itself using the createdb command (i.e., createdb
dcl). dcl is the default name of the database.
- Create the database schema by executing 'psql -e name_of_database
< createdb.sql'
- 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).
- Create the database by executing 'mysqladmin [options] create
dcl' and then 'mysql name_of_database < createdb.mysql'
- Put the DCL source files under the web server DocumentRoot. We used
a subdirectory called 'dcl' for testing.
- 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.
- Copy config.php.default to config.php and edit config.php for your
world. Comments are provided.
- Access the system by using the URL you just created (i.e., http://localhost/dcl/).
- Login as sa with password sa.
- Change sa password through the Admin menu.
- Go to system setup and follow the steps to set up the system.
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.
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.
- Issue reporter sends e-mail to dcl-support@mydomain.com
- MTA for mydomain.com recognizes dcl-support as an alias and forwards
it to the PERL script
- PERL script sections the e-mail into headers, body, and attachments.
- Defaults set from DCL config are: priority, severity, and status
- From: is sectioned into name and e-mail address and inserted into
contact and contact e-mail respectively
- 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.
- The e-mail subject is inserted into the summary
- The e-mail body is inserted into the issue field, minus any attachments
- Using information in the headers, body, and DCL configuration, a ticket
is constructed
- The ticket is created and the files are ``attached'' to it
- Optional e-mail response is sent to originator of e-mail
- Responsible and watchers are notified of the new ticket
- Optionally, responses to the ticket autoresponse e-mail are appended
as ticket resolutions (TODO: this feature is not yet implemented)
This has been used on a PERL installation as old as 5.005_03. PERL
modules required for this to operate include:
- MIME::Base64
- MIME::Parser
- MIME::QuotedPrint
- File::Basename
- DBI
- DBD driver for your SQL server (DBD::mysql or DBD::Pg)
- Net::SMTP
You can install these packages from the CPAN shell (perl -MCPAN -e
shell) by doing install <packagename> (e.g., install DBI)
- 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.
- 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!
- Edit the /etc/aliases (or /etc/postfix/aliases) file.
- Add aliases for each product you would like to route to the gateway.
- Aliases should pipe to the gateway script
- dcl-support: ``|/path/to/dcl-gateway.pl''
- Run the newaliases command
- Restart the postfix daemon (postfix reload)
- 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.
- Edit the /etc/aliases file.
- Add aliases for each product you would like to route to the gateway.
- Aliases should pipe to the gateway script
- dcl-support: ``|/path/to/dcl-gateway.pl''
- Run the newaliases command
- Restart the sendmail daemon (/etc/rc.d/init.d/sendmail restart)
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.
The Admin...System Setup...Configuration page now has a section for
configuring the e-mail gateway.
- 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.
- 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.
- 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.
- 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.
- Gateway Ticket Status - the status to assign tickets created
by the gateway
- Gateway Ticket Priority - the priority to assign tickets
created by the gateway
- Gateway Ticket Severity - the severity to assign tickets
created by the gateway
- 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.
- 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
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
Mikey
2002-01-20