Installation Guide
From EnterTrackDocs
This is the EnterTrack Installation Manual. This page is protected due to excessive spamming. Please use the "discussion" page to suggest changes."
Contents |
Quick Installation
One of EnterTrack's great new features is a setup wizard which will take care of installing and ugprading your EnterTrack installation, even supporting migration from Issue-Tracker 4.0.x.
To access the setup wizard on a new installation, unpack EnterTrack at a location accessible via browser:
cd /var/www/localhost/htdocs tar -zxf entertrack-x.y.z.tar.gz mv entertrack-x.y.z et cd et chmod -R a+w var cache logs sessions conf download
then access setup in the URL corresponding to this location, e.g., http://myhost.mydomain.com/et/setup/. The setup wizard will begin with the test screen, which will check that your system can support EnterTrack. Details of some of these checks are described in the requirements section, below.
When your system passes all tests, click "Next" to begin the setup process. At the next step, setup will ask if you are performing a new installation. If not, see the upgrading section, below, for further assistance.
The subsequent step requests information regarding the database you will use with EnterTrack. If you have an administrative database login (which can create users and databases), EnterTrack can do all of the work of setting up a database and user for you. Otherwise, you may leave the administrator credentials blank, and supply information for a database and user that already exist -- in this case, check the "Already Created" boxes to indicate that EnterTrack should not attempt to create the database and user.
The next step installs the database schema. Assuming that the user for which you supplied credentials has adequate permissions, this step should require no intervention. If you do encounter permissions errors, consult your database administrator.
Next, you will be asked whether to install "Demonstration" data. If you are evaluating EnterTrack, this demonstration data includes a basic setup with one group and two users, which will help you get started quickly. If you are already familiar with EnterTrack and wish to start from nothing, select "Minimal".
After installing the data you requested, the wizard will prompt you with a newly created configuration file. Depending on the permissions you have set for the config directory, setup may or may not be able to install this configuration for you -- consult the options available to you at the bottom of the page.
If all goes well, once the configuration file is installed, you will have a working EnterTrack installation. If not, please contact us -- preferably via entertrack-devel@lists.sourceforge.net, for assistance.
Accessing the root URL should bring you to a login screen. Assuming you installed the demo data, there are two built-in accounts, admin and demo. Both have password demo. The first account is an administrative account, while the second is an employee.
Once you've logged in as admin, you'll want to change the built-in passwords immediately.
Change admin's password, and set up demo with your own information (including your own username and email), then reset its password.
Upgrading EnterTrack
Upgrading EnterTrack, even from Issue-Tracker 4.0.x, is easy with the new setup wizard. Unfortunately, because of the way EnterTrack is structured, simply installing "over" an existing setup will not work. Assuming your existing installation is in a directory named et, the procedure begins with
mv et et-old tar -zxf entertrack-x.y.z.tar.gz mv entertrack-x.y.z et cp et-old/conf/config.php et/conf/config.php cd et chmod -R a+w var cache logs sessions conf download
You now have the new version of EnterTrack in place, but with the old configuration file. The next step is to run the setup wizard, by accessing setup in your EnterTrack URL, e.g., http://myhost.mydomain.com/et/setup/.
The wizard should recognize that you have an existing configuration file, and request the database password from it. If setup jumps right to the test page, check that config.php is in the correct location in your new installation (the cp line, above, is intended to accomplish this).
Once you have supplied the correct password, check that EnterTrack's requirements are met, and that you are performing an upgrade of an existing database. Double-check the database credentials and, if the supplied user cannot modify the database schema, provide administrative credentials as well.
The next page reminds you to back up your database, supplying a template command to do so. Please heed its advice -- while the setup wizard makes every effort to smoothly upgrade your database, there is no "undo" if it makes a mistake.
On the next page, the wizard displays its determination of what schema version is currently installed. For out-of-the-box Issue-Tracker 4.0.x and EnterTrack installations, this is quite reliable. If it has trouble recognizing your schema, then the upgrade is unlikely to work -- you may need to reverse any changes you have made to the shipped schema for your existing installation. Assuming all is well, click "Next" to perform whatever steps are necessary to upgrade your database to the most recent version. This can be a time-consuming process, as many of the schema changes require complex processing of data into new forms.
At the next step, you will be presented with any required changes to your configuration. Note that, while the wizard will retain your existing configuration, it does not make any attempt to retain comments in the configuration file. If you would like to keep your comments, consider applying the changes specified by the wizard by hand.
The following subsections describe upgrade tasks which are not handled by the upgrade wizard.
Migrate Email Settings
EnterTrack's email-handling system has been completely rewritten since the fork from Issue-Tracker. In the new system, the email server should be configured to run a submission script which will transmit the email to EnterTrack, along with any hints as to the group associated with the email.
See the email submission section of this manual or read more in the Administrator's Manual.
Migrate Uploaded Files
If you are upgrading from Issue-Tracker, you must copy or move all subdirectories under the Issue-Tracker file storage location (see constant _FILES_ in Issue-Tracker's conf/const.php) to var/EnterTrack-files/ or whatever directory you have configured for file uploads (in conf/const.php).
Requirements
EnterTrack, as a web-based application, runs within the context of a web server. Most often, this is Apache, but any server which can execute PHP code should fit the bill.
This section of the guide assumes you familiar with the configuration and administration of your web server software. You will need to provide EnterTrack with a directory (the document root) corresponding directly to a URL (the root URL).
PHP
EnterTrack requires at least version 4.3.0 of PHP, available from http://php.net.
The following settings are required (and are enforced by a .htaccess file, which Apache will detect).
- register_globals must be off
- magic_quotes_gpc must be off
- magic_quotes_runtime must be off
PEAR
EnterTrack requires several PEAR modules. PEAR is the PHP Extension and Application Repository, based at http://pear.php.net, and provides easily installed, reusable PHP code for use in applications like this one.
See the PEAR web site for help installing PEAR, if it is not already included with your PHP distribution. Once PEAR is installed, PEAR modules themselves are quite easy to install:
$ pear install MODULE
EnterTrack requires the following modules:
- Date
- Mail_Mime
- MDB2
- MDB2_Driver_mysql or MDB2_Driver_pgsql
Alternately, these packages can be downloaded manually from http://pear.php.net and installed in a place where the PHP interpreter will find them.
If at all possible, upgrade to the latest version of all of the above PEAR modules. Like all complex PHP code, PEAR modules are extraordinariliy buggy. EnterTrack is only tested against the latest stable versions, and is known to fail when run with older versions of most PEAR modules.
Smarty
EnterTrack requires Smarty, the PHP template engine. Smarty is available at http://smarty.php.net and can be installed systemwide, or within EnterTrack. EnterTrack will work with Smarty-2.6.14 and higher, although 2.6.16 is recommended.
See the install directions in the Smarty documentation for more on installing it. If you install Smarty systemwide, you may change the PHP include_path to include the directory containing Smarty.class.php, or edit conf/paths.php to specify that directory as SMARTY_DIR:
define('SMARTY_DIR', '/usr/local/lib/php/Smarty/');
If you do not wish to install Smarty systemwide, install it in a subdirectory smarty of the EnterTrack root directory, and edit the definition of SMARTY_DIR in conf/paths.php to reflect the directory containing Smarty.class.php:
define('SMARTY_DIR', '/home/www/entertrack/smarty/');
(in either case, be sure to include the trailing slash).
Database Server
The issue data managed by EnterTrack is stored in a relational database. Currently, EnterTrack supports the two most popuplar open-source databases, MySQL (http://mysql.com) and PostgreSQL (http://www.postgresql.org). At least one of these servers must be installed and running, and the corresponding libraries must be configured in PHP.
Permissions
If possible, the entire document root should be read-only for the web server, except for the following directories, which must be writeable to the web server:
- logs
- cache
- cache/templates/compiled
- var/EnterTrack-files
if you are using EnterTrack's session management, then sessions should also be writeable.
The exact modes required here depend on your particular installation. On UNIX, if you don't have root access you'll need to grant everyone on the system write access to these directories:
chmod a+wrx logs css cache sessions download var
if you have root access, and know the username under which your webserver runs, you can change the ownership of those directories to your webserver and make them writeable only by that user
chown -R webuser logs css cache sessions download var chmod -R go-w logs css cache sessions download var
On Windows, ensure that the username under which your web server is running has NTFS "Full Control" over those folders. If the server is accessing the folders via a share, ensure that the share permissions are set to "Full Control" for "Everyone".
Email Submission
In order to process incoming emails, you will need to set up a submission script of some sort. If your enterprise's email systems are not under your control, you will need to coordinate closely with your email administrator to select the best solution. This section describes a number of common configurations, one or more of which may work for you. However, every system is unique, so you may need to customize one of these solutions slightly. For background infomation on processing of incoming email, see the Administrator's Manual.
MTA-Invoked Glue Scripts
MTA-invoked glue scripts are run directly by the mail server when a new email arrives. Most UNIX MTAs can do this, although it may be against your enterprise's email server policy. You'll need the following information to configure this sort of script:
- the email address which should deliver messages to EnterTrack (userpart@domain)
- the base URL for your EnterTrack installation (url)
- the shared secret configured in your config.php (shared-secret)
- any other hints (most likely the numeric groupid of the group to which this email address corresponds) (hints)
Postfix Submission with Python
This solution assumes you have Python installed on your mail server. Note that EnterTrack need not be running on your mailserver. You only need to copy submit.py to your mailserver from EnterTrack's email/ directory.
In your Postfix /etc/postfix/aliases, add a line like this:
userpart: |"python /path/to/submit.py hints shared-secret url/email.php"
and run newaliases to update Postfix's tables.
The hints field is usually -g GID, where GID is the numeric groupid of the tracker group into which new issues should be filed.
You may configure an unlimited number of addresses by adding more lines like the above to your aliases file.
Sendmail Submission with Python
This solution is almost identical to that for Postfix with Python, but requires some additional configuration of smrsh.
XXX contribute here!
Mailbox-based Glue Scripts
While MTA-invoked scripts are preferred because they submit emails immediately, in many cases it is not possible (for technical or administrative reasons) to configure the mail server to invoke a script. This is often the case when the mail server is running MS Exchange or a similar product. The alternative is to have the mail server deliver mail to one or more mailboxes, and then periodically check those mailboxes and deliver any new messages to EnterTrack.
To configure this sort of script, you'll need the following information:
- some way to trigger periodic exeuction of a task (not necessarily on the server; at worst, a Scheduled Task on a desktop will do) OR a machine on which a polling script can run uninterrupted (again, a desktop will do in a pinch, with the script placed in "Programs"->"Startup").
- login username, password, and server for each mailbox to be polled
- the base URL for your EnterTrack installation
- the shared secret configured in your config.php
- any other hints (most likely the numeric groupid of the group to which this email address corresponds)
Construct a polling configuration file containing this information. The file format is patterned after the Windows .INI format. It begins with a [global] section which specifies the contact information for the EnterTrack site:
[global] # url of the 'email.php' script in your EnterTrack installation submission-url: http://myserver.hk/entertrack/email.php # shared_secret as configured in EnterTrack's conf/config.php shared_secret: I-M-!-telling # if this directive is specified, the script will not exit but # will re-poll all accounts at this interval (in seconds) daemon-poll-time: 60
This is followed by one or more account specifications, each of which looks like this:
[mymailserver] # type is "pop3", "pop3s" (secure) or "imap" type: pop3 # server is the hostname or IP of the mailserver server: my.mailserver.com # port is the TCP port, needed only if different from the default # port: # username and password are the email login credentials username: tracker password: somethinghardtoguess # optionally, a gid (the numeric ID of the group into which issues should be # filed), issueid, and/or userid may be sent as a "hint": gid = 4 # (these aren't commonly used) #issueid = 1029 #userid = 19
Polling with Cron (or another task scheduler)
If you can schedule the periodic invocation of a script on a reliable machine, you can use this solution.
Copy your polling configuration file to a convenient place on the machine where the script will run. Remove or comment out the daemon-poll-time direcive (if you don't do this, then the script will never exit).
Copy poll.py from EnterTrack's email/ directory to the machine where it will be run. Configure it to run, with the path to the polling configuration file as its single argument, at the frequency you prefer. In a crontab, that might look like this:
* * * * * /usr/bin/python /path/to/poll.py /path/to/poll.conf
On Windows, you may have to schedule a batch file with contents resembling (NOTE: if you have experience running such scripts on Windows, please edit this section!):
C:\PYTHON\PYTHON.EXE C:\PATH\TO\POLL.PY C:\PATH\TO\POLL.CONF
Polling with a Long-Running Script
The other polling option is to run the polling script continuously (as a daemon) on a single machine.
Copy your polling configuration file to a convenient place on the machine where the script will run. Set the daemon-poll-time directive to the number of seconds you would like it to wait between mailbox checks. Check with your mail administrator before setting this to anything lower than a minute or so.
Copy poll.py from EnterTrack's email/ directory to the machine where it will be run. Configure it to run, with the path to the polling configuration file as its single argument, at system startup.
Details
The following sections provide additional details on the installation process. If you run into trouble with the setup wizard, these sections may provide the additional help you need to correct the problem.
Database Setup
The database schema is stored in setup/util/schema.php, and attendant schema upgrade files are stored in setup/util/schema_upgrades.php. These files are interpreted by the setup wizard to perform initial setup and database upgrades. Unfortunately, these files are not easily used outside of the setup wizard. If you are in a situation where the setup wizard cannot operate, the best recourse is to copy your database to a location where you can run the setup wizard, run it, and then copy the resulting configuration file and database back to the original location.
Configuration
EnterTrack's configuration is stored in conf/config.php. This file is dynamically rewritten by the setup wizard, but must be present for EnterTrack to operate -- if it is missing, you will be prompted to run the setup wizard.
Security
For EnterTrack security you have configure the permissions and restriction to access the files of configuration of the following way:
chmod 775 /var/www/html/path/EnterTrack/cache/ chmod 555 /var/www/html/path/EnterTrack/conf/ chmod 555 /var/www/html/path/EnterTrack/css/ chmod 454 /var/www/html/path/EnterTrack/css.php chmod 555 /var/www/html/path/EnterTrack/docs/ chmod 775 /var/www/html/path/EnterTrack/download/ chmod 555 /var/www/html/path/EnterTrack/email/ chmod 454 /var/www/html/path/EnterTrack/email.php chmod 555 /var/www/html/path/EnterTrack/help/ chmod 555 /var/www/html/path/EnterTrack/images/ chmod 555 /var/www/html/path/EnterTrack/includes/ chmod 454 /var/www/html/path/EnterTrack/index.php chmod 454 /var/www/html/path/EnterTrack/initialize.php chmod 555 /var/www/html/path/EnterTrack/locale/ chmod 755 /var/www/html/path/EnterTrack/logs/ chmod 555 /var/www/html/path/EnterTrack/mkrelease.sh chmod 555 /var/www/html/path/EnterTrack/modules/ chmod 775 /var/www/html/path/EnterTrack/sessions/ chmod 555 /var/www/html/path/EnterTrack/setup/ chmod 555 /var/www/html/path/EnterTrack/themes/ chmod 555 /var/www/html/path/EnterTrack/var/ chmod 450 /var/www/html/path/EnterTrack/conf/config.php chmod 454 /var/www/html/path/EnterTrack/conf/const.php chmod 454 /var/www/html/path/EnterTrack/conf/paths.php
And change owner our files and folders:
chown apache.apache /var/www/html/path/EnterTrack/cache/ chown apache.apache /var/www/html/path/EnterTrack/conf chown apache.apache /var/www/html/path/EnterTrack/css chown root.root /var/www/html/path/EnterTrack/css.php chown root.root /var/www/html/path/EnterTrack/docs chown apache.apache /var/www/html/path/EnterTrack/download/ chown root.root /var/www/html/path/EnterTrack/email/ chown root.root /var/www/html/path/EnterTrack/email.php chown root.root /var/www/html/path/EnterTrack/help/ chown root.root /var/www/html/path/EnterTrack/images/ chown root.root /var/www/html/path/EnterTrack/includes chown root.root /var/www/html/path/EnterTrack/index.php chown root.root /var/www/html/path/EnterTrack/initialize.php chown root.root /var/www/html/path/EnterTrack/locale/ chown apache.apache /var/www/html/path/EnterTrack/logs chown root.root /var/www/html/path/EnterTrack/mkrelease.sh chown root.root /var/www/html/path/EnterTrack/modules/ chown apache.apache /var/www/html/path/EnterTrack/ chown root.root /var/www/html/path/EnterTrack/setup/ chown root.root /var/www/html/path/EnterTrack/themes/ chown root.root /var/www/html/path/EnterTrack/test.php chown apache.apache /var/www/html/path/EnterTrack/var/ chown apache.apache /var/www/html/path/EnterTrack/conf/config.php chown apache.apache /var/www/html/path/EnterTrack/conf/const.php chown apache.apache /var/www/html/path/EnterTrack/conf/paths.php
Read more about configuration in the Administrator's Manual.
