DL installation

• Copy the htdocs directory contained in the archive to a directory of choice under your web server.

• Configure the parameters inside include/config.php as needed. This usually means changing the URL and E-Mail of the service.

• Ensure the include and style/include directories are not directly accessible externally. Type http://dl.example.com/include/config.php and verify that you correctly get an "Access Denied" error.

  If you use Apache, the provided .htaccess files should be already sufficient; consult your web server documentation otherwise.

• Create a spool directory that will be used by the service to store the files, user and ticket information. This directory should be outside of the document root of your web server. Fix the permissions so that PHP has read/write access to it.

  In the provided include/config.php this is configured as /var/spool/dl. If you web server runs as "nobody:nogroup", issue:

  mkdir -p -m770 /var/spool/dl
  chgrp nogroup /var/spool/dl
  

  to create correctly this directory.

Database setup

DL needs a database to store the ticket and user information. By default, DL will use an embedded "sqlite" database stored within the spool directory, but some manual setup is still required.

To create the database, you need the sqlite or sqlite3 command, and execute the provided SQL batch for sqlite with the same user as your web server (by using su or sudo if necessary):

cd /var/spool/dl/
sqlite data.sdb < /your-installation-directory/include/scripts/sqlite.sql
chmod 660 data.sdb

If you want to change the database path, or use a real database server, you need to properly configure the $dsn parameter in include/config.php according to your setup.

Upgrading from DL <= 0.3

Upgrading from DL 0.3 or earlier is possible without loosing any data by using the bundled include/scripts/dbupgrade.php script. Proceed as follows:

• Backup your current config.php file and spool directory.

• Overwrite the DL installation directory with the new copy.

• Customize the new config.php file.

• Create a new database as described above in Database setup.

• If you had to change the "$dbHandler" parameter in DL 0.3, copy the same setting into the new configuration file.

• Run dbupgrade.php as your web server user:

  cd /your-installation-directory/include/scripts
  php dbupgrade.php
  

• Test your new setup.

• You can now remove "$dbHandler" from the new configuration file and data.db, user.db from the spool directory.

PHP setup

The following parameters are required to be set in your php.ini (these values are defaults since PHP 5.0, but they might be different in your setup):

• magic_quotes_gpc: must be "Off".
• magic_quotes_runtime: must be "Off".
• date.timezone: must be set to your system preference.

The maximal upload limit is determined by several PHP configuration parameters. Check your php.ini for:

• file_uploads: must be "On".
• upload_tmp_dir: ensure enough space is available.
• upload_max_filesize: change as needed.
• post_max_size: must be at least 1M larger than upload_max_filesize.
• apc.rfc1867: must be "On" for the upload progress-bar to work.

The upload limit as shown in the submission form is determined automatically from the upload_max_filesize parameter. If you are allowed to do so, you can also set these parameters with "ini_set()" directly inside include/config.php (so that it only affects dl).

If PHP was built as an Apache module you can also set them through .htaccess (see http://www.php.net/manual/en/configuration.changes.php).

The upload progress-bar is only available when the PHP APC module in installed, and the apc.rfc1867 setting is explicitly enabled. The PHP APC module is only reported to work on mod_php currently.

Minimal user setup

Once dl has been installed and PHP is set-up correctly, you have to create at least one user to be able to log in. User management is handled through the command line (there is no web-interface yet) by using the bundled useradmin.php utility.

On the server, execute the following commands with the same user as your web server (by using su or sudo if necessary):

cd /your-installation-directory/include/scripts
php useradmin.php add "admin" "true" "change me"

where:

• admin is the user name
• true (or false) sets the administrator status
• change me is the password

Repeat as many times as necessary. You should now be able to use the web service.

Advanced user management

dl supports both "normal" users and "administrators". A normal user can only see and manage tickets created by himself. Administrators can see/manage all the tickets.

dl can use the HTTP authentication provided by your web server. This should be the preferred form of authentication for corporate use since it supports whatever authentication scheme your web server already supports. dl will consider all users as "normal" by default. The only setup required is flagging the administrators with useradmin.php.

Users can be managed through useradmin.php, which should be executed with the same user as the web server. Run:

cd /your-installation-directory/include/scripts
php useradmin.php help

to get a list of all available commands (currently "add", "rm" and "list"). Passwords are optional since they are ignored when using HTTP authentication.

HTTP/External authentication

Only admin.php needs to be password-protected, not the whole directory. With Apache, this can be achieved with the following simple configuration:

<Directory /your-installation-directory>
    <Files admin.php>
       AuthType Basic
       AuthName "Restricted Area"
       ...
       Require valid-user
    </Files>
 </Directory>

To make "Logout" work, you must also set the same authentication realm in both AuthName and include/config.php. Logout with HTTP authentication is not guaranteed to work: users should simply close their browser to clear their session (closing a tab or window is not enough). Currently, logout works as expected on:

• Firefox 3.x
• Safari 4.x
• Google Chrome/Chromium

Logout does not work on:

• Internet Explorer 7/8.
• Opera 9/10.

Only Basic authentication is supported, which transmits the password in clear-text unless you use SSL.

Apache

FastCGI support in Apache up to 2.2.x is severely lacking with all the available modules: mod_fcgi, mod_fcgid (now merged officially into Apache's mod_fcgi) and mod_fastcgi.

• mod_fcgi and mod_fcgid buffer the entire request in memory before handing-off the request to PHP, meaning that the maximal upload limit is bound to your available memory at the time of the request, independently of how PHP is setup. This is a known, old bug that's still present in both mod_fcgi 2.2.14 and mod_fcgid 2.3.4. There is no known work-around: either use mod_php or use a different server.

• mod_fastcgi has been proved to be slow (and sometimes unstable) in most configurations. It is not advisable to use PHP with mod_fastcgi.

• For HTTP/External authentication to work, mod_rewrite needs to be enabled, and a different setup is required, as shown:

  <Directory /your-installation-directory>
    <Files admin.php>
      RewriteEngine on
      RewriteCond %{HTTP:Authorization} ^(.*)
      RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
      AuthType Basic
      AuthName "Restricted Area"
      ...
      Require valid-user
    </Files>
  </Directory>
  

Lighttpd

PHP/FastCGI works fine with Lighttpd 1.4.x without any special setup. The following configuration is required to protect the include directories:

$HTTP["url"] =~ "^/dl(?:/|/.*/)include/" {
  url.access-deny = ( "" )
}

You can also enable external authentication with the following:

auth.require   += ( "/dl/admin.php" => (
    "method"   => "basic",
    "realm"    => "Restricted Area",
    "require"  => "valid-user"
) )