forked from extern/django-helpdesk
244 lines
8.3 KiB
Plaintext
244 lines
8.3 KiB
Plaintext
django-helpdesk - A Django powered ticket tracker for small business.
|
|
|
|
(c) Copyright 2009 Jutda. All Rights Reserved. See LICENSE for details.
|
|
|
|
#########################
|
|
0. Table of Contents
|
|
#########################
|
|
|
|
1. Licensing
|
|
2. Dependencies (pre-flight checklist)
|
|
3. Upgrading from previous versions
|
|
4. Installation
|
|
5. Initial Configuration
|
|
6. Spam filtering
|
|
7. API Usage
|
|
8. Thank You
|
|
|
|
#########################
|
|
1. Licensing
|
|
#########################
|
|
|
|
See the file 'LICENSE' for licensing terms. Note that django-helpdesk is
|
|
distributed with 3rd party products which have their own licenses. See
|
|
LICENSE.3RDPARTY for license terms for included packages.
|
|
|
|
#########################
|
|
2. Dependencies (pre-flight checklist)
|
|
#########################
|
|
1. Python 2.4+
|
|
|
|
2. Django (1.2 or newer)
|
|
|
|
3. An existing WORKING Django project with database etc. If you
|
|
cannot log into the Admin, you won't get this product working.
|
|
|
|
NOTE REGARDING SQLITE AND SEARCHING:
|
|
If you use sqlite as your database, the search function will not work as
|
|
effectively as it will with other databases due to its inability to do
|
|
case-insensitive searches. It's recommended that you use PostgreSQL or MySQL
|
|
if possible. For more information, see this note in the Django documentation:
|
|
http://docs.djangoproject.com/en/dev/ref/databases/#sqlite-string-matching
|
|
|
|
When you try to do a keyword search using sqlite, a message will be displayed
|
|
to alert you to this shortcoming. There is no way around it, sorry.
|
|
|
|
#########################
|
|
3. Upgrading from previous versions
|
|
#########################
|
|
|
|
If you are upgrading from a previous version of django-helpdesk, you should
|
|
read the UPGRADING file to learn what changes you will need to make to get
|
|
the current version of django-helpdesk working.
|
|
|
|
1. Find out your current version of django-helpdesk. In the 'helpdesk' folder,
|
|
use the 'svn' command to find the current revision:
|
|
|
|
svn info .
|
|
|
|
Look for the 'Revision' line, eg:
|
|
|
|
Revision: 92
|
|
|
|
2. Read through the UPGRADE file, looking for any changse made _after_ that
|
|
revision. Apply the commands provided in order from oldest to most recent.
|
|
|
|
3. Restart your web server software (eg Apache) or FastCGI instance, to ensure
|
|
the latest changes are in use.
|
|
|
|
4. Continue to the 'Initial Configuration' area, if needed.
|
|
|
|
#########################
|
|
4. Installation
|
|
#########################
|
|
|
|
1. Place 'helpdesk' in your Python path. I use /var/django, others may use
|
|
/usr/lib/python2.4/site-packages/ or a similar path.
|
|
|
|
2. In your projects' settings.py file, add these lines to the INSTALLED_APPS
|
|
setting:
|
|
'helpdesk',
|
|
'django.contrib.admin',
|
|
|
|
3. In your projects' urls.py file, add this line:
|
|
(r'helpdesk/', include('helpdesk.urls')),
|
|
|
|
You can substitute 'helpdesk/' for something else, eg 'support/' or even ''.
|
|
|
|
4. Ensure the admin line is un-hashed in urls.py:
|
|
# Uncomment this for admin:
|
|
from django.contrib import admin
|
|
admin.autodiscover()
|
|
(r'^admin/(.*)', admin.site.root),
|
|
|
|
If you use helpdesk at the top of your domain (at /), ensure the admin
|
|
line comes BEFORE the helpdesk line.
|
|
|
|
5. In your project directory (NOT the helpdesk directory) run
|
|
./manage.py syncdb
|
|
to create database tables
|
|
|
|
6. Inside your MEDIA_ROOT folder, create a new folder called 'helpdesk' and
|
|
copy the contents of helpdesk/htdocs/ into it. Alternatively, create a
|
|
symlink:
|
|
ln -s /path/to/helpdesk/htdocs /path/to/media/helpdesk
|
|
|
|
This application assumes all helpdesk media will be accessible at
|
|
http://MEDIA_URL/helpdesk/
|
|
|
|
7. Inside your MEDIA_ROOT folder, inside the 'helpdesk' folder, is a folder
|
|
called 'attachments'. Ensure your web server software can write to this
|
|
folder - something like this should do the trick:
|
|
|
|
chown www-data:www-data attachments/; chmod 700 attachments
|
|
(substitute www-data for the user / group that your web server runs
|
|
as, eg 'apache' or 'httpd')
|
|
|
|
If all else fails ensure all users can write to it:
|
|
|
|
chmod 777 attachments/
|
|
|
|
This is NOT recommended, especially if you're on a shared server.
|
|
|
|
8. Ensure that your 'attachments' folder has directory listings turned off,
|
|
to ensure users don't download files that they are not specifically linked
|
|
to from their tickets.
|
|
|
|
If you are using Apache, put a .htaccess file in the 'attachments' folder
|
|
with the following content:
|
|
|
|
Options -Indexes
|
|
|
|
You will also have to make sure that .htaccess files aren't being ignored.
|
|
|
|
Ideally, accessing http://MEDIA_URL/helpdesk/attachments/ will give you a
|
|
403 access denied error.
|
|
|
|
#########################
|
|
5. Initial Configuration
|
|
#########################
|
|
|
|
1. Visit http://yoursite/admin/ and add a Helpdesk Queue. If you wish,
|
|
enter your POP3 or IMAP server details.
|
|
|
|
IMPORTANT NOTE: Any tickets created via POP3 or IMAP mailboxes will DELETE
|
|
the original e-mail from the mail server.
|
|
|
|
2. Visit http://yoursite/helpdesk/ (or other path as defined in your urls.py)
|
|
|
|
3. If you wish to automatically create tickets from the contents of an e-mail
|
|
inbox, set up a cronjob to run scripts/get_email.py on a regular basis.
|
|
|
|
Don't forget to set the relevant Django environment variables in your
|
|
crontab:
|
|
|
|
*/5 * * * * /path/to/helpdesksite/manage.py get_email
|
|
|
|
This will run the e-mail import every 5 minutes
|
|
|
|
IMPORTANT NOTE: Any tickets created via POP3 or IMAP mailboxes will DELETE
|
|
the original e-mail from the mail server.
|
|
|
|
4. If you wish to automatically escalate tickets based on their age, set up
|
|
a cronjob to run scripts/escalate_tickets.py on a regular basis:
|
|
|
|
0 * * * * /path/to/helpdesksite/manage.py escalate_tickets
|
|
|
|
This will run the escalation process hourly, using the 'Escalation Hours'
|
|
setting for each queue to determine which tickets to escalate.
|
|
|
|
5. If you wish to exclude some days (eg, weekends) from escalation calculations, enter
|
|
the dates manually via the Admin, or setup a cronjob to run
|
|
scripts/create_escalation_exclusions on a regular basis:
|
|
|
|
0 0 * * 0 /path/to/helpdesksite/manage.py create_escalation_exclusions.py --days saturday,sunday --escalate-verbosely
|
|
|
|
This will, on a weekly basis, create exclusions for the coming weekend.
|
|
|
|
6. Log in to your Django admin screen, and go to the 'Sites' module. If the
|
|
site 'example.com' is listed, click it and update the details so they are
|
|
relevant for your website.
|
|
|
|
7. If you do not send mail directly from your web server (eg, you need to
|
|
use an SMTP server) then edit your settings.py file so it contains your
|
|
mail server details:
|
|
|
|
EMAIL_HOST = 'XXXXX'
|
|
EMAIL_HOST_USER = 'YYYYYY@ZZZZ.PPP'
|
|
EMAIL_HOST_PASSWORD = '123456'
|
|
|
|
You're now up and running!
|
|
|
|
#########################
|
|
7. Spam filtering
|
|
#########################
|
|
|
|
django-helpdesk includes a copy of `akismet.py' by Michael Foord, which lets
|
|
incoming ticket submissions be automatically checked against either the
|
|
Akismet or TypePad Anti-Spam services.
|
|
|
|
To enable this functionality, sign up for an API key with one of the following
|
|
serviceS:
|
|
|
|
Akismet: http://akismet.com/
|
|
Save your API key in settings.py as AKISMET_API_KEY
|
|
Note: Akismet is only free for personal use. Paid commercial accounts are
|
|
available.
|
|
|
|
TypePad AntiSpam: http://antispam.typepad.com/
|
|
Save your API key in settings.py as TYPEPAD_ANTISPAM_API_KEY
|
|
This service is free to use, within their terms and conditions.
|
|
|
|
If you have either of these settings enabled, the spam filtering will be
|
|
done automatically. If you have *both* settings configured, TypePad will
|
|
be used instead of Akismet.
|
|
|
|
Example configuration in settings.py:
|
|
|
|
TYPEPAD_ANTISPAM_API_KEY = 'abc123'
|
|
|
|
#########################
|
|
7. API Usage
|
|
#########################
|
|
|
|
django-helpdesk includes an API accessible via HTTP POST requests, allowing
|
|
you to create and alter tickets from 3rd party software and systems.
|
|
|
|
For usage instructions and command syntax, see the file
|
|
templates/helpdesk/api_help.html, or visit http://helpdesk/api/help/.
|
|
|
|
#########################
|
|
8. Thank You
|
|
#########################
|
|
|
|
While this started as a project to suit my own needs, since publishing the
|
|
code a number of people have made some fantastic improvements and provided
|
|
bug fixes and updates as the Django codebase has moved on and caused small
|
|
portions of this application to break.
|
|
|
|
To these people, my sincere thanks:
|
|
|
|
David Clymer <http://djangopeople.net/vezult/>
|
|
Chris Etcp
|
|
Nikolay Panov
|