Difference between revisions of "WebIssues/Installation"

Revision as of 18:02, 8 July 2010

This is the installation guide for WebIssues Server version 1.0.

The installation guide for version 0.8.5 is available in the online manual or in your local copy of the manual.

Note that the alpha development version should be used for testing purposes only. It is not possible to update and older version to an alpha version and it will not be possible to update the alpha version to a later version. Also the alpha version of the server is only compatible with the same version of the desktop client.

Requirements

• Web server with PHP version 5.2 or newer (http://php.net/)
• The following PHP extensions:
  • mbstring (required)
  • mysqli (required when using MySQL database)
• One of the following database servers:
  • MySQL version 4.1 or newer
  • SQL Server 2005 or newer (supported on Windows only)

The system is being tested with Apache and IIS servers. Other web servers may also work, but are not officially supported.

Quick Steps

1. Unpack the entire WebIssues Server package to the web server's document root directory.
2. Create a database and a user account with sufficient privileges to create tables in that database.
3. Make sure that the data/ subdirectory is writable for the web server.
4. Point your browser to the admin/setup/install.php page and follow the instructions.

Database

You can use an existing database instead of creating a new one. Just ensure that the tables used by the WebIssues Server have a unique prefix to avoid clashes with other tables. This way you can also install multiple instances of the server sharing a single database. It is also possible to create multiple instances of the server within a single installation (see Multiple Sites for more information).

The database user used by the WebIssues Server to login to the database must have sufficient privileges to create tables. The simplest solution for MySQL is to grant ALL PRIVILEGES to the database; for SQL Server assign the user to the database owner role. Refer to the database documentation for more information about privileges.

In version 1.0 you don't have to edit the configuration file manually because the setup script will create it for you. If you want to change the connection options later, either modify the configuration file or delete it and run the setup script again. For security reasons it is not possible to run the setup script if the configuration file exists.

Security

It is very important to make sure that the data/ and common/data/ directories are not accessible to unauthorized users. Especially the configuration file, which contains credentials for the database server, should be protected from unauthorized access. You can use the General Information page in the Administration Panel to check if the configuration file is protected (JavaScript support is required for this function to work).

The source package contains .htaccess files which can be used with Apache and compatible web servers to protect access to those directories. Make sure that Apache is configured to handle the .htaccess file. Set the AllowOverride option to All in the configuration file for the Apache server or the appropriate virtual host or directory to enable these settings.

If you are using Windows and IIS server, go to Authorization Rule section for these two directories and create a rule to deny access from all users and remove all other rules. You can also create a Web.config file if you are using IIS 7 or newer (see below).

For more security it is recommended that the data files are stored outside of the WebIssues Server directory. See WebIssues configuration for more information.

Error Pages

The WebIssues server contains two scripts which can be used to handle 403 Forbidden and 404 Not Found errors. If you are using IIS, you can also handle the 500 Server Error. The error handler scripts are:

• common/errors/handle403.php
• common/errors/handle404.php
• common/errors/handle500.php

Those script not only provide user friendly error information which is consistent with the look of the WebIssues application, but they also add appropriate messages to the WebIssues event log.

The .htaccess file distributed with the source package configures the error handlers for Apache. You may need to modify the path if the WebIssues Server is not installed in the root location of the web server.

If you are using IIS, go to Error Pages section and add or modify the error pages for appropriate status codes. You can also use the Web.config file (see below).

Files with .inc.php and .html.php are protected from being executed directly through the URL, but they output a blank screen and no error is logged. The .htaccess file configures Apache to generate a 403 Forbidden error when these files are accessed. You can configure Request Filtering in IIS to achieve a similar behavior.

Note that for security reasons WebIssues by default does not show detailed error information on the error pages. Error details are stored in the WebIssues event log and can be viewed through the Administration Panel. To make debugging easier, you may enable showing error details in the WebIssues configuration.

IIS Configuration

To install WebIssues Server on Windows with IIS you first need to install PHP. The easiest way to do that is to use the Web Platform Installer. You should also install the Windows Cache Extension for significant improvement of performance. Visit http://php.iis.net/ for more information.

If you are using Windows with IIS verson 7 or newer, you can quickly configure the security settings and error pages by copying the attached Web.config file to the root directory of the WebIssues Server. Note that you may need to modify the paths of the error pages if the WebIssues Server is not installed in the root location of the web server.

Alternatively you can host WebIssues Server on Windows using XAMPP, which includes Apache, MySQL and PHP. Visit http://www.apachefriends.org/en/xampp.html for more information.

Known Issues

This is a list of most important issues in the current development version of WebIssues:

• The server doesn't work when using PHP 5.3 and MySQL database and fails to install on such configuration. See http://webissues.mimec.org/node/233 for a solution to this problem.