Difference between revisions of "WebIssues/Configuration"

Latest revision as of 13:44, 8 May 2020

NOTE: This Wiki is related to old versions of WebIssues which are no longer developed. For information about the current version of WebIssues, please see the official website, the GitHub repository and the WebIssues Guide.

Most configuration options can be configured at run time using the Administration Panel and the configuration file containing database connection is automatically created by the setup script. In some cases it may be useful to edit other options, for example when data files are stored in a non-default location or when multiple instances of the server are used within a single installation.

Such advanced options can be configured by creating a data/site.ini file. Note that you should never modify the common/data/site.ini file which contains default settings and will be overwritten when you update the application.

Directories

By default all data files, including the database configuration file, attachment storage and debugging log, are stored in the data subdirectory. Such configuration may be unsafe and it is recommended to place those files in a different location, outside of the WebIssues Server directory.

For example, if WebIssues Server is installed in /webissues/www directory and data files are located in /webissues/data directory, put the following in the site.ini file:

[global]
site_dir = "/webissues/data/sites/%site%"
debug_file = "/webissues/data/log/%site%.log"

Make sure that these directories exist and are accessible and writable for the web server.

Multiple Sites

The %site% placeholder in file and directory paths is replaced with the virtual name of the WebIssues site (usually 'default'). It possible to host multiple instances of the WebIssues Server within the same installation by attaching it to multiple sites. Individual sites can be distinguished by host name, port number and/or virtual path. For example if the production (default) server is accessible at http://www.example.com/ and the test server is accessible at http://test.example.com:8080/, add the following section to the site.ini file:

[test]
match = test.example.com:8080

The match mask consists of a host name, optional port and optional path. If no site matching the full host name is found, parent hosts are tried (e.g. example.com and com). The same rule applies to the virtual path. If no mask matches, the '*' mask is tried, which is normally assigned to the 'default' site.

If a site can be reached using a few different URLs, you can create a section which acts as an alias for another section:

[test2]
match = test2.example.com
alias = test

All sites inherit settings from the 'global' group, but you can modify individual settings for each site, for example enable debugging on the test server:

[test]
match = test.example.com:8080
debug_level = DEBUG_ALL

Each site has a separate database, attachments storage directory and configuration file. After creating a new site, navigate to the appropriate setup script for that site (for example, http://test.example.com:8080/admin/setup/install.php), enter database connection details, and the configuration file will be automatically created. You can install multiple sites in a single database by using unique table name prefixes.

If a cron job is used to send email notifications, the name of the site can be passed as the additional argument. When the cron job is executed through the URL, it will automatically determine the appropriate site.

Debugging

WebIssues only shows general error pages and stores detailed information in the event log. To make development and debugging easier, it may be useful to enable displaying error details directly on the error pages. To do that, add the following directive to the site.ini file:

[global]
debug_info = on

For troubleshooting it may also be useful to turn on logging detailed information to the log file using the following option:

[global]
debug_level = DEBUG_ALL

You can do this either for all sites (using the global group) or for each site individually.

The log file is created in data/log directory by default; its location can be configured using the debug_file option as shown above. All available debugging levels are defined in the system/core/debug.inc.php file. Remember to turn debugging off on production servers as it may negatively affect the security and performance of the application.