WebIssues/Installation

This page contains platform specific installation notes for WebIssues Server 1.0. For general information about installing the server, refer to the WebIssues manual.

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.

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.

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

    <directoryBrowse enabled="false" />

    <defaultDocument enabled="true">
      <files>
        <clear />
        <add value="index.php" />
      </files>
    </defaultDocument>

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

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

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

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.