The WebIssues Server Manual
Issue tracking and team collaboration system
Home » Installation Guide
« Security settings
Credits and License »

## Configuring WebIssues

This chapter explains the configuration options available in the `config/config.inc.php` file. Use the configuration template to create this file and edit it to your needs before running the setup or upgrade.

### Note

Make sure that the configuration file is not accessible to anyone except the web server process. See the Security chapter for more information.

### Database connection

Depending on the type of the database server, you have to select the appropriate database engine. There are currently four available engines:

`mysql`

  Engine for MySQL. Requires the `mysql` PHP extension.

`mysqli`

  Engine for MySQL. Requires the `mysqli` PHP extension and MySQL version 4.1 or newer.

`pgsql`

  Engine for PostgreSQL. Requires the `pgsql` PHP extension.

`mssql`

  Engine for SQL Server. Only supported on Windows; requires PHP5.

`firebird`

  Engine for Firebird. Requires the `interbase` PHP extension.

Configuring the database connection requires entering four parameters: the database server host name, the database name and the user name and password used to authenticate the connection.

The `db_host` is usually a computer name or IP address. It may be followed by a semicolon and port number if a non-standard port is used. When connecting to a local MySQL server, the MySQL client will automatically use a Unix local socket or Windows named pipe if it's available. To connect to the PostgreSQL server using a local socket, leave the `db_host` option blank.

In case of SQL Server 2005 and SQL Server 2005 Express, the `db_host` option should include the computer name and server instance, for example `SERVER\SQLEXPRESS`. Also make sure that TCP/IP connections are enabled in the server's configuration and in case of SQL Server 2005 Express that it has a static port number assigned.

In case of Firebird, the `db_database` option is usually the full path of the database file. Use `localhost` as `db_host` unless the database is located on a different server.

Usually the WebIssues Server connects to the database using SQL authentication, which requires passing a login and password which have to be stored in the configuration file. You can also configure SQL Server or PostgreSQL to use integrated authentication (called identity authentication in PostgreSQL). In that case leave the `db_user` and `db_password` option blank and give appropriate permissions to the database for the account used by the web server process.

If the database is shared between multiple applications, enter a unique prefix in the WebIssues configuration to avoid clashes with other database name. The prefix should begin begin with a letter and contain only letters, digits and underscore characters. You can also create multiple instances of the WebIssues Server sharing the same database, but using a different prefix.

### Attachment storage

By default all attachments larger than 4000 bytes are stored in the files system instead of the database. This improves performance and decreases the size of the database. You can adjust the threshold value by changing the `storage_min_size` option in the configuration file.

The attachment files are stored by default in the `storage` subdirectory of the directory where the WebIssues Server is installed. You have to create that directory and make sure it's readable and writable for the web server. You can change the location of the attachment storage to a location outside the server's root directory to improve security or if you want to store the files on a different disk partition. In that case modify the `storage_path` option to enter the path of the storage directory.

You can also disable file storage and force storing all attachments in the database. To do that, clear the default value of the `storage_path` option. Note that database storage has significantly worse performance for large attachments.

If you want the server to be able to handle large file attachments, you may have to change the `upload_max_size` and `post_max_size` parameters in the PHP configuration. Refer to the PHP manual for more details. Also adjust the memory limit and execution time limit for the PHP scripts.

If you are storing large attachments in the database, you may also need to increase the limit of query size on the database server. For example when using MySQL, change the `max_allowed_packet` option in the server's configuration.

### Notifications

The server can periodically send email notifications about new and modified issues, based on user preferences and subscriptions. For this feature to work, the `cron.php` script must be periodically executed. Since the mechanisms for executing periodic tasks and for sending emails are not always available on every host, this feature is optional and disabled by default.

In order to enable notifications, you have to perform three steps:

1. Make sure that the `cron.php` script is periodically executed, for example using a cron job or a Scheduled Task on Windows (see below).

2. Make sure that the mailing engine is correctly configured (see Mailing).

3. Set the `notify_enabled` parameter in configuration file to 1.

Under Linux usually the `crontab` file can be used to configure jobs executed periodically. For example, adding the following line to this file will run the `cron.php` script every hour:

0 * * * * php /var/www/html/cron.php

You may need to adjust the path to the `php` executable and to the script file.

Under Windows you can create a Scheduled Task to execute the script. Enter the following command to run:

C:\PHP\php.exe cron.php

Ensure that the path to `php.exe` is correct and set the start directory to the location where the server is installed. Use the advanced settings on the Schedule tab to configure the task to run with desired frequency.

Depending on the preferences of individual users, notifications can be sent as weekly or daily summaries or immediately when at least one subscribed issue is added or modified, but not more often than a defined interval. That interval can be configured using the `notify_min_span` parameter, in minutes; by default it is two hours. Obviously notifications can only be sent as often as the cron script runs, so this parameter should not be smaller than the interval of the cron job execution.

As checking for notifications may take some time if many users are using them, the cron script should not be executed too often. The minimum allowed interval is 5 minutes, as the time of script execution is always rounded to nearest multiple of that time span.

The content of notification emails is composed dynamically based on a template file. There are two predefined templates, one for plain text emails and another for HTML emails with simple formatting. The template to be used can be selected using the `notify_template` parameter in the configuration file. You can also create your own templates by copying and modifying one of the predefined ones. To make sure your custom template is not deleted when you upgrade the server, put it into another directory.

### Mailing

The WebIssues Server has two engines for sending emails. Use the `mail_engine` parameter to select the engine to use:

`standard`

  Engine using the built-in PHP mailing function.

`smtp`

  Engine allowing to use an external SMTP server.

In order for the standard engine to work, PHP must be configured to use the `sendmail` tool on Linux or the local SMTP server on Windows. Refer to the PHP manual for more information about configuring mailing. In addition, the `mail_from` parameter must be set to a valid email address which is accepted by the mailing function.

The SMTP engine can connect to an external SMTP server, for example gmail, in order to send emails. It can be useful if emails cannot be sent directly from the host on which the WebIssues Server is running. To configure the SMTP engine, besides the `mail_from` parameter you also have to enter the host name or IP address of the server and the user name and password for authentication (unless the server allows anonymous connections). If a secure connection is required, set the `smtp_secure` parameter to either `ssl` or `tls`, depending on which protocol is supported by the server. You may also need to set a different port number (port 25 is usually used for unsecured connections, secured connections often use port 465 instead).

### Logging

By default the server's log files are written to the `log` subdirectory of the directory where the WebIssues Server is installed. You have to create that directory and make sure it's writable for the web server. You can change the location of the log files to another directory, for example `/var/log`. In that case modify the options to enter the paths of the log files. Remove the default values to disable logging.

The main log files are:

`log_errors`

  File used to log errors and warnings.

`log_cron`

  File used to log executions of the cron script and performed operations.

The two additional log files, `log_commands` and `log_sql`, are only useful for debugging purposes and should never be enabled on production servers.

« Security settings
Credits and License »

Copyright © 2007-2009 WebIssues Team