Difference between revisions of "WebIssues/Configuration"

Revision as of 12:12, 28 June 2010

This is the configuration guide for WebIssues Server version 1.0.

Information about configuring version 0.8.5 of the server is available in the online manual or in your local copy of the manual.

Directories

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 setting and will be overwritten when you update the application.

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:

[default]
config_file = "/webissues/data/config/%site%.ini"
storage_dir = "/webissues/data/storage/%site%"
debug_file = "/webissues/data/log/%site%.log"

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

You can disable the storage directory by adding a storage = off directive to the site.ini file. In that case attachments will always be stored in the database.

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 (sites) within the same installation of the WebIssues server. 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/, put the following in the site.ini file:

[default]

[test]
match_host = test.example.com
match_port = 8080

The recognized filtering directives are match_host, match_port and match_path. You can use '*' as a wildcard for parts of the host name or path (for example, test.*.com matches both test.example.com and test.foobar.com). All sites inherit settings from the default site, but you can modify individual settings for each site. You can temporarily disable a site by adding a enabled = off directive to its settings.

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 create multiple instances in a single database by using unique table name prefixes.

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:

[default]
debug_info = on

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

[default]
debug_level = DEBUG_ALL

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.

Note that if you are using IIS, you may need to configure the Error Pages feature and change the Error Response behavior to Detailed or DetailedLocalOnly, otherwise a generic error page will be always displayed instead of the detailed error information.