WebIssues/Installation

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.

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.1 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.

The following information can be used to set up the database using command line tools.

MySQL

1. Create the database (dbauser is the login of the database administrator, database is the name of the database to create):

mysqladmin -u dbauser -p create database

You will be prompted for the database administrator's password.

2. Connect to the database server:

mysql -u dbauser -p

From the MySQL command prompt execute the following query to create a user with access to the database (user is the user's login, password is the user's password and database is the name of the database):

GRANT ALL PRIVILEGES ON database.* TO 'user'@'localhost' IDENTIFIED BY 'password';

3. Execute the following query to activate the new permissions:

FLUSH PRIVILEGES;

PostgreSQL

1. Create the user account (user is the user's login):

createuser --pwprompt --encrypted --no-adduser --no-createdb user

You will be prompted for the password for the new user. Note that you have to log in as a user with appropriate permissions to manage the PostgreSQL server.

2. Create the database (user is the user's login, database is the name of the database to create):

createdb --encoding=UNICODE --owner=user database

SQL Server

1. Connect to the database server:

sqlcmd.exe -U dbauser -P dbapassword

Replace dbauser and dbapassword with the login and password of the database administrator.

2. Execute the following queries to create a user's login and the database (user is the user's login, password is the user's password and database is the name of the database to create):

CREATE LOGIN user WITH PASSWORD = 'password';
GO
CREATE DATABASE database;
GO

3. Execute the following queries to assign appropriate permissions for the database to the user (user is the user's login, database is the name of the database):

USE database;
GO
EXEC sp_grantdbaccess 'user';
GO
EXEC sp_addrolemember 'db_owner', 'user';
GO

Web Server

Copy the contents of the server installation package to the root directory of the web server. You can also set up a virtual directory or virtual host.

Apache

The source package contains the following .htaccess file which can be used with Apache and compatible web servers to configure permissions, default handler and error handlers:

# protect include files and templates
<FilesMatch (\.(inc\.php|html\.php|svn-base)$)>
  Order allow,deny
  Deny from all
</FilesMatch>

# do not show directory listings
Options -Indexes

# set the default handler
DirectoryIndex index.php

# set error handlers
ErrorDocument 401 /common/errors/handle401.php
ErrorDocument 403 /common/errors/handle403.php
ErrorDocument 404 /common/errors/handle404.php

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. You may also put some additional configuration options to this file depending on your server configuration; refer to the web server's manual for more information.

If the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to ErrorDocument URLs.

The data/ and common/data/ directories should be protected from accessing from the web. These directories also contain .htaccess files with the following content:

# deny access to all files in this directory
Order allow,deny
Deny from all

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

It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of Apache for more details.

The mod_security module may cause problems with WebIssues, for example block the Desktop Client or reject legitimate requests containing certain words. If you have mod_security installed, make sure that it is correctly configured and disable the rules that cause problems. Refer to mod_security documentation for more details. Alternatively, you can simply disable mod_security completely by adding the following lines to the main .htaccess file:

<IfModule mod_security.c>
SecFilterEngine Off
SecFilterScanPOST Off
</IfModule>

<IfModule mod_security2.c>
SecRuleEngine Off
</IfModule>

IIS

Make sure that PHP and webcache extension is correctly configured. It is recommended to use the Microsoft Web Platform Installer to install PHP support for IIS. Visit http://php.iis.net/ for more information.

In order to protect the data/ and common/date/ directories from accessing from the web, 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 configure Request Filtering to disable access to files with .inc.php and .html.php extensions.

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

It is also recommended to set up custom Error Pages to handle HTTP 401, 403 and 404 errors, in order to provide user friendly error information which is consistent with the look of the WebIssues application, and to log appropriate messages in the WebIssues Event Log. The error handler scripts provided by the WebIssues Server are:

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

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.

You can also use the following Web.config file to configure your IIS server:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
 <system.webServer>
    <!-- protect include files and templates -->
    <security>
      <requestFiltering>
        <hiddenSegments>
          <clear />
          <add segment=".htaccess" />
          <add segment=".svn" />
          <add segment="web.config" />
        </hiddenSegments>
        <denyUrlSequences>
          <clear />
          <add sequence=".html.php" />
          <add sequence=".inc.php" />
        </denyUrlSequences>
      </requestFiltering>
    </security>

    <!-- do not show directory listings -->
    <directoryBrowse enabled="false" />

    <!-- set the default handler -->
    <defaultDocument enabled="true">
      <files>
        <clear />
        <add value="index.php" />
      </files>
    </defaultDocument>

    <!-- set error handlers -->
    <httpErrors errorMode="Custom">
      <remove statusCode="401" subStatusCode="-1" />
      <remove statusCode="403" subStatusCode="-1" />
      <remove statusCode="404" subStatusCode="-1" />
      <error statusCode="401" prefixLanguageFilePath="" path="/common/errors/handle401.php" responseMode="ExecuteURL" />
      <error statusCode="403" prefixLanguageFilePath="" path="/common/errors/handle403.php" responseMode="ExecuteURL" />
      <error statusCode="404" prefixLanguageFilePath="" path="/common/errors/handle404.php" responseMode="ExecuteURL" />
    </httpErrors>
  </system.webServer>

  <!-- protect data directory -->
  <location path="data">
    <system.webServer>
      <security>
        <authorization>
          <remove users="*" roles="" verbs="" />
          <add accessType="Deny" users="*" />
        </authorization>
      </security>
    </system.webServer>
  </location>

  <!-- protect common data directory -->
  <location path="common/data">
    <system.webServer>
      <security>
        <authorization>
          <remove users="*" roles="" verbs="" />
          <add accessType="Deny" users="*" />
        </authorization>
      </security>
    </system.webServer>
  </location>
</configuration>

Note that if the server is installed in a subdirectory or a virtual directory, you should add appropriate prefixes to the error page URLs.

It is also recommended to enable compression and static contents caching in order to improve the performance of the server. Refer to the documentation of IIS for more details.

Cron Job

On 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/job.php

You may need to adjust the path to the php executable and to the script file. See the documentation of cron for more details.

On Windows you can create a task in the Task Scheduler that executes the script. Enter php.exe (with appropriate path) as the program, cron/job.php as the argument and the location where the WebIssues Server is installed as the start directory. Use the advanced settings on the Triggers tab to configure the task to repeat with desired interval.